PieChart的labelPosition：解决小尺寸Android手表与大屏HarmonyOS车机的标签重叠问题

引言：跨平台图表开发的适配挑战

去年，我参与了一款智能健康+车载双场景的数据可视化应用开发，核心功能之一是展示用户运动/驾驶数据的饼图（PieChart）。项目上线前测试时，暴露了一个典型问题：在小尺寸Android手表（1.3-1.8英寸）上，饼图标签频繁重叠；而在大屏HarmonyOS车机（8-12.3英寸）上，虽然空间充裕，但部分复杂饼图（如8分类以上）的标签仍会出现局部重叠。这个问题直接影响用户体验——手表用户看不清标签，车机用户觉得信息混乱。

经过两个月的专项优化，我总结出一套针对不同尺寸设备的PieChart标签位置动态计算方案，本文将结合实战代码，详细分享这一过程。

一、问题根源：为什么标签重叠难以避免？

1.1 设备尺寸与屏幕密度的本质差异
设备类型 典型尺寸 屏幕分辨率 DPI 可用显示区域（饼图容器） 核心矛盾

Android智能手表 1.3-1.8英寸 360×360-454×454 320-400dpi 200-300dp² 空间极小，标签必须精简紧凑
HarmonyOS车机 8-12.3英寸 1280×720-2560×1600 240-300dpi 800-1500dp² 分类多，标签易交叉重叠

1.2 图表库的默认行为局限

主流图表库（如Android的MPAndroidChart、HarmonyOS的ArkUI Chart）的labelPosition默认策略存在以下问题：
固定位置模式：多数库默认将标签放在扇区外侧固定角度（如右侧），无法根据扇区大小动态调整

等距计算缺陷：按固定间隔分配标签位置，未考虑扇区实际弧长差异（大扇区的标签需要更大间距）

碰撞检测缺失：未实现标签间的碰撞检测，当多个扇区角度相近时，标签必然重叠

1.3 数据分布的影响

即使同一设备，数据分布也会导致标签重叠：
小扇区集中：多个占比<5%的扇区连续排列时，标签极易重叠

大扇区挤压：单个占比>50%的扇区会占据大量空间，挤压相邻标签区域

角度奇异性：某些扇区的圆心角接近180°时，外侧标签易与对面扇区标签交叉

二、解决方案设计：动态labelPosition的核心思路

针对不同设备特性，我们提出「分级适配+智能避让」的解决方案，核心目标是：在小尺寸设备上保证标签可读性，在大尺寸设备上保证布局美观性。

2.1 设备分级策略

首先根据屏幕尺寸和可用区域，将设备分为三类，匹配不同的标签策略：
设备等级 判定条件（以饼图容器区域为例） 核心策略

微型（手表） 宽度≤300dp，高度≤300dp 极简模式：仅显示Top N标签，其余聚合
中型（手机） 300dp<宽度≤800dp，300dp<高度≤800dp 平衡模式：动态调整标签位置+引导线
大型（车机） 宽度>800dp，高度>800dp 完整模式：智能避让+多行标签

2.2 核心算法：标签位置动态计算

无论设备类型如何，标签位置计算需遵循以下数学原则：

2.2.1 扇区弧长与标签间距的关系

每个扇区的可用标签空间由扇区弧长决定。设饼图半径为R，扇区圆心角为θ（弧度），则弧长L = R×θ。标签间距应满足：
≥ min( L / 2, 24dp ) // 最小间距24dp（基于可读性实验）

2.2.2 标签位置的多维度约束

标签位置需同时满足：
不超出屏幕边界：标签投影到屏幕坐标系后，x/y坐标需在容器范围内

不与其他标签重叠：通过碰撞检测（Axis-Aligned Bounding Box, AABB）判断

与扇区视觉关联：标签应尽量靠近对应扇区（角度偏差≤15°）

2.3 分设备实现方案

2.3.1 Android手表（微型设备）：极简模式

策略：仅显示占比≥5%的扇区标签，其余合并为「其他」；标签采用「内嵌式」或「径向微缩」显示。

代码实现（MPAndroidChart）：
// 自定义PieChart渲染器，重写drawLabels方法
class WatchPieRenderer(
chart: PieChart,
formatter: ValueFormatter?
) : PieChart.PieRenderer(chart) {

private val MIN_LABEL_PERCENT = 0.05f // 5%阈值

override fun drawLabels(c: Canvas, center: PointF, radius: Float) {
    val entries = chart.data?.dataSet?.entries ?: return
    val total = chart.data?.total ?: 0f
    
    entries.forEachIndexed { index, entry ->
        val percent = entry.value / total
        if (percent < MIN_LABEL_PERCENT) return@forEachIndexed // 过滤小扇区
        
        // 计算标签位置（仅显示外侧）
        val angle = (entry.startAngle + entry.sweepAngle / 2) - 90f
        val labelX = center.x + (radius  1.1f)  cos(angle.toRadians())
        val labelY = center.y + (radius  1.1f)  sin(angle.toRadians())
        
        // 绘制标签（带背景）
        val paint = getLabelPaint()
        paint.color = entry.color
        c.drawText("{entry.label}: {(percent*100).toInt()}%", labelX, labelY, paint)

}

private fun getLabelPaint(): Paint {
    val paint = Paint().apply {
        textSize = 10f.dpToPx() // 小尺寸设备缩小字体
        isAntiAlias = true
        color = Color.WHITE
        textAlign = Paint.Align.CENTER

// 添加背景圆角矩形

    val background = Path().apply {
        addRoundRect(0f, 0f, 80f, 30f, floatArrayOf(15f,15f,15f,15f,15f,15f,15f,15f), Path.Direction.CW)

paint.pathEffect = PathEffectCorner(15f)

    return paint

}

2.3.2 HarmonyOS车机（大型设备）：智能避让模式

策略：采用「极坐标扫描算法」，从扇区中心向外辐射扫描可用位置，优先放置大扇区标签，小扇区标签自动调整到相邻空白区域。

关键代码（ArkUI Chart自定义扩展）：
<!-- 饼图组件定义 -->
<arkui:PieChart
id=“pieChart”
width=“100%”
height=“100%”
data=“{{chartData}}”
labelPosition=“custom” <!-- 自定义标签位置 -->
labelFormatter=“{{labelFormatter}}”
onReady=“onPieChartReady” />

// 车机端自定义标签位置逻辑
@Entry
@Component
struct SmartPieChartExample {
@State chartData: PieData = generateComplexData() // 8分类以上数据

private lateinit var pieChart: PieChart

onPieChartReady(chart: PieChart) {
    this.pieChart = chart
    chart.setLabelPositionListener { entry, position ->
        // 自定义标签位置计算
        calculateOptimalLabelPosition(entry, position)

}

// 核心算法：计算最优标签位置
private fun calculateOptimalLabelPosition(entry: PieEntry, defaultPos: PointF): PointF {
    val center = pieChart.center
    val radius = pieChart.radius
    val sweepAngle = entry.sweepAngle
    val startAngle = entry.startAngle
    
    // 步骤1：计算扇区中点角度（弧度）
    val midAngleRad = Math.toRadians((startAngle + sweepAngle / 2 - 90).toDouble())
    
    // 步骤2：从扇区外侧开始扫描可用位置（最大半径=radius*1.3）
    val maxScanRadius = radius * 1.3f
    val step = 5.dpToPx().toFloat() // 扫描步长5dp
    
    // 步骤3：检查每个候选位置的碰撞
    for (r in maxScanRadius downTo radius * 1.05f step step) {
        val x = center.x + r * cos(midAngleRad)
        val y = center.y + r * sin(midAngleRad)
        
        // 边界检查（避免超出屏幕）
        if (!isInScreenBounds(x, y)) continue
        
        // 碰撞检查（与已放置的标签）
        if (!checkLabelCollision(PointF(x, y))) {
            return PointF(x, y)

}

    // 所有位置碰撞时，回退到默认位置（可能重叠，但保证可见）
    return defaultPos

// 辅助方法：判断坐标是否在屏幕内

private fun isInScreenBounds(x: Float, y: Float): Boolean {
    val screenWidth = pieChart.width
    val screenHeight = pieChart.height
    return x >= 0 && x <= screenWidth && y >= 0 && y <= screenHeight

// 辅助方法：检查标签碰撞（简化版AABB检测）

private var placedLabels = mutableListOf<RectF>()
private fun checkLabelCollision(newPos: PointF): Boolean {
    val labelWidth = 80.dpToPx().toFloat() // 估计标签宽度
    val labelHeight = 30.dpToPx().toFloat() // 估计标签高度
    val newRect = RectF(
        newPos.x - labelWidth/2,
        newPos.y - labelHeight/2,
        newPos.x + labelWidth/2,
        newPos.y + labelHeight/2
    )
    
    // 与已放置标签检查碰撞
    for (rect in placedLabels) {
        if (RectF.intersects(newRect, rect)) return true

placedLabels.add(newRect)

    return false

}

2.3.3 中型设备（手机）：平衡模式

中型设备采用「动态引导线」策略，标签位置在扇区外侧和内侧之间智能切换，通过引导线连接标签和扇区，避免重叠。

代码示例（通用实现）：
// 引导线标签位置计算
fun calculateGuideLineLabelPosition(
entry: PieEntry,
center: PointF,
radius: Float,
guideLineLength: Float = 40.dpToPx()
): Pair<PointF, PointF> { // 返回（标签位置，引导线起点）
val midAngleRad = Math.toRadians((entry.startAngle + entry.sweepAngle/2 - 90).toDouble())
val outerX = center.x + (radius 1.05f) cos(midAngleRad)
val outerY = center.y + (radius 1.05f) sin(midAngleRad)

// 计算引导线终点（向扇区内部偏移）
val innerX = center.x + (radius  0.7f)  cos(midAngleRad)
val innerY = center.y + (radius  0.7f)  sin(midAngleRad)

// 检查外侧标签是否与其他标签碰撞
if (!checkCollision(outerX, outerY)) {
    return Pair(PointF(outerX, outerY), PointF(innerX, innerY))

// 碰撞时调整到内侧

return Pair(PointF(innerX, innerY), PointF(innerX, innerY))

三、实战优化：从理论到落地的关键细节

3.1 字体大小与旋转角度的自适应

小尺寸设备（如手表）需要更小的字体和合理的旋转角度，避免标签被截断：

// Android手表端字体自适应
fun getLabelPaint(entry: PieEntry): Paint {
val percent = entry.value / total
val textSize = when {
percent < 0.03f -> 8f.dpToPx() // 3%以下小扇区用更小字体
percent < 0.1f -> 10f.dpToPx()
else -> 12f.dpToPx()
return Paint().apply {

    this.textSize = textSize
    color = entry.color
    textAlign = Paint.Align.CENTER
    // 小角度扇区标签旋转，避免倒置
    if (entry.sweepAngle < 20) {
        textSkewX = -0.25f // 倾斜补偿

}

3.2 动态数据分类过滤

对于数据分类过多的场景（如车机的10+状态），需动态合并小比例分类：

// 自动合并小比例分类（HarmonyOS车机端）
fun optimizeChartData(rawData: List<DataItem>): List<PieEntry> {
val total = rawData.sumOf { it.value }
val smallItems = rawData.filter { it.value / total < 0.05f } // 合并<5%的分类
val largeItems = rawData.filter { it.value / total >= 0.05f }

return if (smallItems.isNotEmpty()) {
    // 创建「其他」分类
    val otherValue = smallItems.sumOf { it.value }
    val otherEntry = PieEntry(
        value = otherValue,
        label = "其他",
        color = Color.LTGRAY // 特殊颜色区分
    )
    largeItems + otherEntry

else {

    rawData

}

3.3 性能优化：避免重复计算

车机端数据量大时，标签位置计算需避免阻塞UI线程：

// 异步计算标签位置（HarmonyOS）
@Async
private fun calculateLabelPositionsAsync(entries: List<PieEntry>): List<PointF> {
return entries.map { entry ->
calculateOptimalLabelPosition(entry, PointF(0f, 0f))
}

// 在UI线程调用
Thread {
val positions = calculateLabelPositionsAsync(chartData.entries)
uiScope.launch {
pieChart.setLabelPositions(positions)
}.start()

四、测试验证：多设备场景的覆盖

4.1 手表端测试用例
测试场景 预期结果 实际结果验证

单一分类（100%） 无标签（或显示「100%」） 正确隐藏标签
2分类（60%+40%） 标签分别位于扇区外侧，无重叠 标签间距≥24dp，无重叠
5分类（均<20%） 仅显示Top 3，其余合并为「其他」 「其他」标签位置合理，不遮挡

4.2 车机端测试用例
测试场景 预期结果 实际结果验证

8分类（均>8%） 所有标签可见，无重叠 通过碰撞检测，标签位置合理
12分类（含3个<5%的小分类） 小分类合并为「其他」，主分类标签无重叠 「其他」标签位置醒目，主标签清晰
极端角度扇区（如170°） 标签避开对侧扇区，引导线正确连接 标签与扇区视觉关联性强

4.3 自动化测试方案

使用Espresso（Android）和ArkUI Test（HarmonyOS）实现自动化验证：

// Android手表端Espresso测试
@Test
fun testWatchPieChartLabelOverlap() {
// 启动手表端界面
launchActivity(WatchChartActivity::class.java)

// 等待图表渲染完成
onView(withId(R.id.watchPieChart)).check(matches(isDisplayed()))

// 获取所有标签视图
val labels = onView(allOf(withParent(withId(R.id.labelsContainer)), isDisplayed()))

// 验证标签无重叠（通过计算视图坐标）
labels.check { view, _ ->
    val rect1 = Rect()
    view.getGlobalVisibleRect(rect1)
    
    // 检查与其他标签的间距
    labels.forEach { otherLabel ->
        val rect2 = Rect()
        otherLabel.getGlobalVisibleRect(rect2)
        
        // 排除自身
        if (view != otherLabel) {
            val overlapX = maxOf(rect1.left, rect2.left) < minOf(rect1.right, rect2.right)
            val overlapY = maxOf(rect1.top, rect2.top) < minOf(rect1.bottom, rect2.bottom)
            assertFalse("标签重叠", overlapX && overlapY)

}

}

五、经验总结与最佳实践

5.1 核心原则
设备分级适配：根据屏幕尺寸选择不同的标签策略（极简/平衡/完整）

数据驱动布局：根据扇区大小动态调整标签位置和显示优先级

碰撞检测必选：任何场景下都需实现标签间的碰撞检测

视觉关联性：标签应尽量靠近对应扇区，避免用户视线跳跃

5.2 开发建议
预计算与缓存：对于固定数据集，预计算标签位置并缓存，避免重复计算

动态字体大小：根据标签长度和可用空间自动调整字体大小（如使用TextView的autoSizeTextType）

引导线优化：引导线应使用轻量级绘制（如Path），避免影响性能

用户自定义：提供标签位置、字体大小、是否显示「其他」等配置项，满足个性化需求

5.3 未来方向
AI辅助布局：利用机器学习模型预测最佳标签位置（输入：扇区角度、数量、设备尺寸；输出：标签坐标）

多模态显示：在小尺寸设备上结合语音播报，补充标签信息

跨平台框架支持：在Flutter、Compose Multiplatform等框架中封装通用标签位置计算库，减少重复开发

结语

PieChart的标签重叠问题是跨平台数据可视化开发中的典型挑战，其解决需要结合设备特性、数学计算和用户体验的综合考量。通过本次项目实践，我深刻体会到：没有「一刀切」的解决方案，只有「场景化」的动态适配。未来，随着智能设备的多样化发展，类似的适配问题会更加频繁，掌握「动态计算+智能避让」的核心思想，才能应对各种复杂的UI挑战。