鸿蒙5莓创仪表盘图表series属性详解

大家好，欢迎回来鸿蒙5莓创图表组件的专场，我们这一期来讲解McGaugeChart（仪表盘）的series属性详细用法。本文将逐一拆解所有核心属性，覆盖作用、类型、默认值、可选值、使用场景，并搭配完整代码案例。文末还会拓展实际开发案例，助你快速掌握高阶用法！

一、show属性

作用：控制仪表盘整体显示状态类型：Boolean 默认值：true 可选值：true（显示）、false（隐藏）场景：需要动态切换仪表盘可见性时使用，例如根据用户操作隐藏图表代码案例：

series: [{
  show: false, // 隐藏仪表盘
  data: [{ name: '鸿蒙', value: 90 }]
}]

二、name属性

作用：定义图例名称，用于多仪表盘场景的标识类型：String 默认值：空字符串可选值：任意自定义文本场景：多个仪表盘叠加时区分不同数据组代码案例：

series: [{
  name: '系统性能',
  data: [{ name: 'CPU使用率', value: 75 }]
}]

三、radius属性

作用：设置仪表盘半径，控制图表大小类型：String | Number 默认值：'60%' 可选值：百分比（如'80%'）或固定数值（如200）场景：适配不同屏幕尺寸或与其他组件布局时调整大小代码案例：

series: [{
  radius: '80%', // 占据容器80%的半径
  data: [{ name: '内存占用', value: 60 }]
}]

四、center属性

作用：设置仪表盘中心点坐标类型：Array 默认值：['50%', '50%']（居中）可选值：百分比或像素值，如['30%', 100] 场景：调整仪表盘在容器内的位置代码案例：

series: [{
  center: ['30%', '40%'], // 横向30%位置，纵向40%位置
  data: [{ name: '网络延迟', value: 45 }]
}]

五、startAngle与endAngle属性

作用：定义仪表盘弧形的起始和结束角度类型：Number（弧度值）默认值：

startAngle: -(Math.PI / 4) * 5（225度）
endAngle: Math.PI / 4（45度）可选值：任意弧度值，如-Math.PI/2到Math.PI 场景：自定义弧形范围，如制作半圆形或全环形仪表盘代码案例：

series: [{
  startAngle: -Math.PI / 2, // 起始角度为-90度（正上方）
  endAngle: Math.PI * 1.5,  // 结束角度为270度（形成完整环形）
  data: [{ name: '完成率', value: 90 }]
}]

六、min与max属性

作用：设置仪表盘数值范围类型：Number 默认值：min: 0，max: 100 可选值：任意数值，如min: -50，max: 200 场景：非百分比场景（如温度范围-20℃~40℃）代码案例：

series: [{
  min: -20,
  max: 40,
  data: [{ name: '温度', value: 25 }]
}]

七、splitNum属性

作用：设置仪表盘刻度分割数量类型：Number 默认值：5 可选值：正整数（如10表示分成10段）场景：需要更精细的刻度显示时代码案例：

series: [{
  splitNum: 10, // 显示10个刻度
  data: [{ name: '精度指标', value: 85 }]
}]

八、data属性

作用：核心数据配置，支持多层级嵌套类型：Array 默认值：空数组子属性详解：

name：数据项名称（String）
value：数据值（Number）
gradient：渐变颜色数组（如['#FF0000', '#00FF00']）

场景：单仪表盘或多层嵌套仪表盘代码案例：

series: [{
  data: [
    { name: '外层', value: 70, gradient: ['#FF0000', '#FFA500'] },
    { name: '中层', value: 50, radius: '40%' },
    { name: '内层', value: 30, radius: '20%' }
  ]
}]

九、dataItemStyle属性

作用：配置数据项弧线样式类型：Object 子属性详解：

lineWidth：弧线宽度（Number，默认10）
fill：填充颜色（String，默认根据主题色）
lineCap：线段端点样式（'butt'、'round'、'square'，默认'butt'）

场景：自定义弧线外观代码案例：

series: [{
  dataItemStyle: {
    lineWidth: 20,
    lineCap: 'round', // 圆角端点
    fill: '#FFB6C1'
  },
  data: [{ name: '美观度', value: 95 }]
}]

十、axisTick与axisLabel属性

作用：控制刻度线及标签的显示与样式类型：Object axisTick子属性：

show：是否显示刻度（Boolean，默认true）
length：刻度长度（Number，默认5）
style：样式配置（颜色、宽度等）

axisLabel子属性：

show：是否显示标签（Boolean，默认true）
formatter：标签格式化函数（如(val) => val + '%'）
distance：标签与刻度的距离（Number，默认10）

场景：隐藏刻度或自定义标签内容代码案例：

series: [{
  axisTick: {
    show: false // 隐藏刻度线
  },
  axisLabel: {
    show: true,
    formatter: (val) => `${val}单位`,
    distance: 20
  },
  data: [{ name: '自定义标签', value: 60 }]
}]

十一、pointer属性

作用：配置指针样式及行为类型：Object 子属性详解：

show：是否显示指针（Boolean，默认true）
valueIndex：指向的数据索引（Number，默认0）
style：指针样式（颜色、缩放比例等）

场景：多数据层时指定指针指向代码案例：

series: [{
  pointer: {
    show: true,
    valueIndex: 1, // 指向第二个数据项
    style: { fill: '#FF0000', scale: [0.8, 0.8] }
  },
  data: [{ name: '主指标', value: 70 }, { name: '副指标', value: 50 }]
}]

十二、details属性

作用：配置数据标签的显示细节类型：Object 子属性详解：

show：是否显示（Boolean，默认true）
formatter：自定义文本格式化函数
offset：位置偏移（如[0, 20]）
precision：小数精度（Number，默认0）
style：文本样式（字体、颜色等）

场景：显示动态计算值或复合内容代码案例：

series: [{
  details: {
    show: true,
    formatter: (dataItem) => `${dataItem.name}：${dataItem.value}%`,
    offset: [0, 40],
    style: { fontSize: 24, fill: '#333' }
  },
  data: [{ name: '完成度', value: 85 }]
}]

十三、backgroundArc属性

作用：配置背景弧线的显示与样式类型：Object 子属性详解：

show：是否显示（Boolean，默认true）
fill：背景颜色（String，默认'#F0F0F0'）
lineWidth：弧线宽度（Number，默认与数据项弧线一致）

场景：弱化背景或实现透明效果代码案例：

series: [{
  backgroundArc: {
    show: false // 隐藏背景弧线
  },
  data: [{ name: '极简风格', value: 90 }]
}]

实际案例：多层级渐变环形仪表盘

@Entry
@Component
struct DashboardExample {
  @State options: Options = new Options({
    title: { text: '系统健康度' },
    series: [{
      startAngle: -Math.PI / 2,
      endAngle: Math.PI * 1.5,
      arcLineWidth: 25,
      data: [
        { name: '硬件', value: 80, gradient: ['#FF6B6B', '#FF8E53'] },
        { name: '软件', value: 65, radius: '70%', gradient: ['#4ECDC4', '#45B7AF'] },
        { name: '网络', value: 90, radius: '50%', gradient: ['#96C93D', '#79B753'] }
      ],
      axisTick: { show: false },
      axisLabel: { show: false },
      pointer: { show: false },
      dataItemStyle: { lineCap: 'round' },
      details: {
        formatter: (item) => `${item.name}：${item.value}%`,
        style: { fontSize: 18, fill: '#666' }
      }
    }]
  });

  build() {
    Column() {
      McGaugeChart({ options: this.options })
    }
  }
}

效果说明：三层渐变环形仪表盘，隐藏刻度与指针，通过不同半径实现堆叠效果，细节标签显示具体数值。

好，这期讲到这里就结束了，希望大家通过本文能全面掌握McGaugeChart的series属性配置技巧。在实际开发中，灵活组合这些属性可以创造出高度定制化的仪表盘效果，无论是数据监控大屏还是移动端性能展示都能游刃有余！遇到问题欢迎在评论区交流，我们下期再见！