HarmonyOS 鸿蒙Next 5莓创图表饼图legend属性详解

HarmonyOS 鸿蒙Next 5莓创图表饼图legend属性详解 大家好，欢迎回来鸿蒙5莓创图表组件的专场，我们这一期来讲解组合图组件中的legend属性的完整用法。本文会以分点拆解的方式讲解每个属性的作用、类型、默认值、可选值、适用场景，并提供可直接运行的代码案例。最后还会拓展一个电商数据可视化综合案例，建议先收藏再阅读！

一、基础显示控制

• show属性
  • 作用：控制图例整体显示或隐藏
  • 类型：Boolean
  • 默认值：true
  • 场景：当图表空间紧张或不需要解释数据分类时隐藏

legend: { show: false } // 完全隐藏图例

• orient属性
  • 作用：设置图例排列方向
  • 类型：String
  • 默认值：horizontal
  • 可选值：horizontal（水平排列）、vertical（垂直排列）
  • 场景：横向适合顶部/底部布局，纵向适合左右两侧布局

legend: { orient: 'vertical' } // 纵向排列常用于侧边栏仪表盘

二、精准定位系统

• left/right/top/bottom属性
  • 作用：控制图例容器的定位
  • 类型：String | Number
  • 默认值：auto（自动计算位置）
  • 可选值：像素值（如20）或百分比（如'30%'）
  • 场景：需要固定图例位置时使用

legend: { 
  left: '15%',   // 左侧留出15%空间
  top: 50        // 距离顶部50像素
}

三、图形定制化

• icon属性
  • 作用：定义图例项前的标识图形
  • 类型：String
  • 默认值：roundRect
  • 可选值：rect（矩形）、circle（圆形）、roundRect（圆角矩形）
  • 场景：圆形适合饼图，矩形适合柱状图

legend: { icon: 'circle' } // 电商用户画像常用圆形标识

• iconRadian属性
  • 作用：设置roundRect类型图标的圆角弧度
  • 类型：Number
  • 默认值：2
  • 场景：需要柔和视觉效果时增大该值

legend: { 
  icon: 'roundRect',
  iconRadian: 10 // 大圆角适合年轻化设计风格
}

• itemWidth/itemHeight属性
  • 作用：控制图例标识图形的尺寸
  • 类型：Number
  • 默认值：8
  • 场景：需要突出图例或适配特殊设计

legend: { 
  itemWidth: 15,  // 加宽标识
  itemHeight: 20  // 增高标识
}

四、间距与对齐

• itemGap属性
  • 作用：设置图例项之间的间距
  • 类型：Number
  • 默认值：10
  • 场景：紧凑布局时减小该值

legend: { itemGap: 5 } // 移动端小屏适配

• itemTextGap属性
  • 作用：设置图形与文本的间距
  • 类型：Number
  • 默认值：5
  • 场景：需要强调文本时增大间距

legend: { itemTextGap: 10 } // 教育类图表常用

• align属性
  • 作用：控制纵向布局时图标与文本对齐方式
  • 类型：String
  • 默认值：auto
  • 可选值：left、right
  • 场景：需要强制对齐时指定

legend: { 
  orient: 'vertical',
  align: 'right' // 金融图表常用右对齐
}

五、交互与状态管理

• selectAble属性
  • 作用：控制图例项是否可点击筛选
  • 类型：Boolean
  • 默认值：true
  • 场景：需要动态过滤数据时启用

legend: { selectAble: false } // 演示模式禁用交互

• data属性
  • 作用：手动指定图例项文本内容
  • 类型：Array
  • 默认值：[]（自动从数据集获取）
  • 场景：需要自定义分类名称时使用

legend: { 
  data: ['安卓用户', 'iOS用户'] // 移动端数据分析专用
}

六、深度样式定制

• textStyle属性
  • 作用：配置图例文本基础样式
  • 子属性：
    • fontFamily：字体类型（默认sans-serif）
    • fontWeight：字重（默认normal）
    • fontSize：字号（默认30）
    • color：字体颜色（默认#333）
    • formatter：文本格式化（支持函数）
  • 场景：统一品牌视觉规范

textStyle: {
  fontFamily: 'Microsoft YaHei',
  fontSize: 24,
  color: '#1890ff',
  formatter: (name) => `${name} ▶` // 添加指示符号
}

• iconStyle属性
  • 作用：配置图例标识图形的默认样式
  • 类型：Object
  • 场景：需要特殊颜色或渐变时使用

iconStyle: {
  color: 'linear-gradient(90deg, #ff6b6b, #ff8787)' // 渐变色标识
}

• textUnselectedStyle/iconUnselectedStyle属性
  • 作用：配置未选中状态的样式
  • 子属性：与选中状态相同
  • 场景：突出显示当前选中项

textUnselectedStyle: {
  color: '#ccc',   // 未选项文字灰化
  fontSize: 20     // 缩小字号
},
iconUnselectedStyle: {
  color: '#eee'    // 未选项图标淡化
}

七、高级渲染控制

• rLevel属性
  • 作用：设置渲染层级优先级
  • 类型：Number
  • 默认值：20
  • 场景：解决元素遮挡问题时调整

legend: { rLevel: 99 } // 确保图例始终在最顶层

• animationCurve/animationFrame属性
  • 作用：控制图例显示动画的曲线和帧数
  • 类型：String | Number
  • 默认值：easeOutCubic 和 0（无动画）
  • 场景：需要个性化动效时配置

animationCurve: 'elasticOut', // 弹性动画
animationFrame: 30           // 增加动画流畅度

八、综合实战案例

电商数据大屏配置示例：

const legendConfig = {
  show: true,
  orient: 'horizontal',
  left: 'center',
  top: '8%',
  icon: 'circle',
  itemWidth: 18,
  itemHeight: 18,
  itemGap: 25,
  textStyle: {
    fontSize: 16,
    color: '#fff',
    formatter: '{value}用户'
  },
  iconStyle: {
    color: '#ee6666'
  },
  textUnselectedStyle: {
    color: 'rgba(255,255,255,0.4)'
  },
  data: ['00后', '90后', '80后']
};

好，这期讲到这里就结束了，希望大家通过这篇深度解析，能够像搭积木一样自由配置莓创图表的图例系统。建议在真实项目中多尝试不同属性的组合效果，遇到问题随时回看本文。下期我们将揭秘「动态数据更新」的黑科技，敬请期待！