syncfusion-react-bullet-chart

实现 Syncfusion React 子弹图

用于实现和自定义 Syncfusion 的 React Bullet Chart 组件的技能。子弹图是一种紧凑的数据可视化组件，用于将主要度量值（实际值）与定性范围内的目标度量值进行比较。

何时使用此技能

在用户需要以下功能时使用此技能：

• 显示带目标比较的绩效指标或 KPI
• 创建展示实际值与目标值的紧凑数据可视化
• 使用定性范围（差、良好、优秀）可视化目标达成进度
• 构建包含节省空间的绩效指标的仪表板
• 显示与比较度量值（目标条形）的特征度量值（实际条形）
• 实现水平或垂直子弹图
• 在紧凑布局中显示多个指标
• 创建支持键盘导航的无障碍图表可视化

组件概览

子弹图由以下部分组成：

• 值条（特征度量）：正在测量的主要数据／实际值
• 比较条（目标标记）：目标值或比较值
• 定性范围：表示绩效等级的背景色带（例如，差、合格、良好）
• 定量刻度：显示数值测量的坐标轴
• 标题／副标题：描述图表的文本

文档与导航指南

入门

📄 阅读： references/getting-started.md

API 参考

📄 阅读： references/api.md

• 汇总各示例中使用的 BulletChartComponent 属性、方法、事件和指令

数据绑定

📄 阅读： references/data-binding.md

值条配置

📄 阅读： references/value-bar.md

• 值条（特征度量）概览及用途
• 将数据源中的 valueField 映射为值
• 实际条形的类型（Rect、Dot）
• 使用 type 属性更改条形类型
• 使用 valueBorder（颜色、宽度）自定义边框
• 使用 valueFill 自定义填充颜色
• 使用 valueHeight 自定义高度
• 从 dataSource 动态绑定颜色
• 每种自定义选项的完整示例

比较条配置

📄 阅读： references/comparative-bar.md

• 比较条（目标度量）概览
• 将数据源中的 targetField 映射为目标值
• 目标条形的类型（Circle、Cross、Rect）
• 使用 targetTypes 属性更改目标类型
• 使用 targetColor 自定义目标外观
• 使用 targetWidth 属性调整目标宽度
• 从 dataSource 绑定目标颜色
• 每种目标类型的完整示例

范围配置

📄 阅读： references/ranges.md

• 表示定性区间（良好、较差、合格）的范围
• 使用 BulletRangeCollectionDirective 和 BulletRangeDirective
• 使用 end 属性设置范围边界
• 了解最小值如何作为范围起点
• 为不同质量等级配置多个范围
• 使用 color 属性自定义颜色
• 使用 opacity 属性调整不透明度
• 包含多个彩色范围的完整示例

标题与副标题

📄 阅读： references/titles.md

• 使用 title 属性添加图表标题
• 添加副标题以提供更多信息
• 使用 titlePosition 属性（Left、Right、Top、Bottom）设置标题位置
• 默认位置（Top）的行为
• 使用 titleStyle（颜色、不透明度、字体属性）自定义标题样式
• 使用 subtitleStyle（颜色、不透明度、字体属性）自定义副标题样式
• 每种位置的完整示例
• 字体自定义示例（大小、字体系列、粗细、样式）

工具提示

📄 阅读： references/tooltips.md

• 默认工具提示行为（默认隐藏）
• 使用 tooltip.enable 属性启用工具提示
• 将 BulletTooltip 模块注入服务
• 悬停时显示实际值和目标值
• 使用 template 属性创建自定义模板
• 在模板中使用 ${target} 和 ${value} 占位符
• 自定义工具提示外观（fill、border、textStyle）
• 自定义工具提示文本的字体
• 默认和自定义工具提示的完整示例

数据标签

📄 阅读： references/data-labels.md

• 用于标识实际条形值的数据标签
• 使用 dataLabel.enable 属性启用数据标签
• 标签显示行为和位置
• 使用 labelStyle 属性自定义样式
• 字体属性（size、family、weight、style）
• 调整颜色和不透明度
• 带样式数据标签的完整示例

坐标轴自定义

📄 阅读： references/axis-customization.md

• 自定义 MajorTickLines（width、height、color、useRangeColor）
• 自定义 MinorTickLines（width、height、color、useRangeColor）
• 使用 tickPosition（Inside、Outside）设置刻度位置
• 使用 labelFormat 设置标签格式（globalize 格式：n1、n2、p1、c1 等）
• 展示常见数字、百分比和货币格式的格式表
• 使用 enableGroupSeparator 为千位数启用分组分隔符
• 使用 ${value} 占位符自定义标签格式
• 使用 labelPosition（Inside、Outside）设置标签位置
• 使用 opposedPosition 属性设置相对位置
• 使用 categoryField 为 X 轴设置类别标签
• 使用 categoryLabelStyle 和 labelStyle 设置类别标签样式
• 使用 useRangeColor 使标签与范围颜色匹配
• 每项坐标轴功能的完整示例

图表尺寸

📄 阅读： references/dimensions.md

• 使用内联样式和 CSS 配置容器大小
• 使用 width 和 height 属性设置图表尺寸
• 固定尺寸使用像素值
• 使用百分比尺寸实现相对于容器的响应式行为
• 默认尺寸行为（高度为 126px，宽度为窗口宽度）
• 容器尺寸和直接设置尺寸的完整示例

自定义选项

📄 阅读： references/customization.md

• 使用 orientation 属性设置方向（Horizontal、Vertical）
• 默认方向为 Horizontal
• 使用 enableRtl 属性支持从右到左（RTL）布局
• 使用 animation 属性配置动画（duration、delay）
• 为实际值条和目标值条设置线性动画
• 使用 theme 属性支持主题
• 可用的 Syncfusion 主题
• 每项自定义功能的完整示例

无障碍功能

📄 阅读： references/accessibility.md

• 符合无障碍标准（ADA、Section 508、WCAG 2.2）
• 含兼容状态的无障碍功能表
• WAI-ARIA 属性和模式（img role、button role、aria-label、aria-pressed）
• 支持键盘交互（Tab、Shift+Tab、Ctrl+P）
• 支持屏幕阅读器
• 支持用于国际化的从右到左（RTL）布局
• 符合颜色对比度要求
• 支持移动设备
• 使用 accessibility-checker 和 axe-core 工具进行测试
• 无障碍演示示例参考

快速入门示例

import { BulletChartComponent, BulletRangeCollectionDirective, BulletRangeDirective, BulletTooltip, Inject } from '@syncfusion/ej2-react-charts';

function App() {
  const data = [
    { value: 270, target: 250 }
  ];

  return (
    <BulletChartComponent
      id="bulletChart"
      dataSource={data}
      valueField="value"
      targetField="target"
      title="Revenue"
      minimum={0}
      maximum={300}
      interval={50}
      tooltip={{ enable: true }}
    >
      <BulletRangeCollectionDirective>
        <BulletRangeDirective end={150} color="red" />
        <BulletRangeDirective end={250} color="yellow" />
        <BulletRangeDirective end={300} color="green" />
      </BulletRangeCollectionDirective>
      <Inject services={[BulletTooltip]} />
    </BulletChartComponent>
  );
}

常见模式

包含多个指标的性能仪表板

垂直显示多个子弹图表，以展示各种 KPI：

const metrics = [
  { value: 270, target: 250, category: 'Revenue' },
  { value: 85, target: 100, category: 'Profit' },
  { value: 180, target: 150, category: 'Sales' }
];

// Map each metric to a separate BulletChartComponent with categoryField

根据数据动态设置颜色

直接从数据源绑定颜色：

const data = [
  { value: 270, target: 250, valueColor: '#5B5FC7', targetColor: '#646464' }
];

<BulletChartComponent
  dataSource={data}
  valueFill="valueColor"
  targetColor="targetColor"
/>

自定义工具提示模板

使用自定义 HTML 显示格式化的值：

<BulletChartComponent
  tooltip={{
    enable: true,
    template: '<div><b>Actual:</b> ${value}<br/><b>Target:</b> ${target}</div>'
  }}
/>

响应式布局

使用基于百分比的尺寸构建响应式仪表板：

<BulletChartComponent
  width="100%"
  height="80px"
/>

关键属性

属性	类型	用途
dataSource	Array	图表的数据集合
valueField	string	实际值／特征值对应的字段名称
targetField	string	目标值／对比值对应的字段名称
minimum	number	定量刻度的最小值
maximum	number	定量刻度的最大值
interval	number	轴标签之间的间隔
title	string	图表标题文本
subtitle	string	图表副标题文本
type	string	数值条形形状：'Rect' 或 'Dot'
targetTypes	string[]	目标条形形状：'Circle'、'Cross'、'Rect'
orientation	string	图表方向：'Horizontal' 或 'Vertical'
width	string	图表宽度（像素或百分比）
height	string	图表高度（像素或百分比）
enableRtl	boolean	启用从右到左的渲染
theme	string	应用 Syncfusion 主题
tooltip	object	工具提示配置，包含 enable、template、fill、border、textStyle
dataLabel	object	数据标签配置，包含 enable、labelStyle

常见用例

KPI 仪表板

使用子弹图展示多个绩效指标：

• 为每项指标设置不同的目标
• 使用红色／黄色／绿色范围表示绩效水平
• 添加类别标签以显示指标名称
• 启用工具提示以显示详细信息

销售绩效跟踪器

将实际销售额与目标进行比较：

• 将营收数据映射到 valueField
• 在 targetField 中设置季度／月度目标
• 配置范围以区分未达标、达标和超额完成
• 使用数据标签显示精确值

进度指示器

通过可视化上下文展示目标达成进度：

• 使用基于百分比的范围（0-50%、50-75%、75-100%）
• 自定义颜色以符合品牌规范
• 添加动画以实现流畅的过渡效果
• 将标题放在左侧，以实现紧凑布局

对比分析

并排比较多个项目：

• 使用垂直方向以节省空间
• 为所有图表设置一致的刻度
• 应用类别标签以便清晰识别
• 自定义目标类型（Circle、Cross）以便区分

移动端仪表板

创建响应式、适合触控的可视化：

• 使用基于百分比的尺寸
• 增大条形的触控区域
• 启用针对移动端优化的工具提示
• 使用无障碍工具进行屏幕阅读器测试

边缘情况与故障排除

数据未显示：

• 确认 valueField 和 targetField 与数据源的属性名称一致
• 检查 dataSource 是否为包含有效对象的数组
• 确保 minimum／maximum 覆盖数据范围

范围不可见：

• 从 @syncfusion/ej2-react-charts 导入 BulletRangeCollectionDirective 和 BulletRangeDirective
• 按升序设置结束值
• 确认结束值在 minimum／maximum 范围内

工具提示无法使用：

• 注入 BulletTooltip 模块：<Inject services={[BulletTooltip]} />
• 将 tooltip.enable 设为 true
• 检查 tooltip 对象配置是否正确

标题／副标题重叠：

• 将 titlePosition 调整为 Left、Right、Top 或 Bottom
• 增大图表尺寸（width／height）
• 自定义 titleStyle 和 subtitleStyle 的字号

轴标签被截断：

• 增大图表宽度或高度
• 将标签格式调整为更短的表示形式（例如，使用 'n1' 而不是完整数字）
• 使用 enableGroupSeparator 提高可读性

实施清单

• 安装 @syncfusion/ej2-react-charts 包
• 导入 BulletChartComponent 和指令
• 准备包含数值字段和目标字段的数据
• 配置 dataSource、valueField、targetField
• 为刻度设置 minimum、maximum 和 interval
• 使用 BulletRangeCollectionDirective 添加范围
• 根据需要配置标题和副标题
• 启用并自定义工具提示（注入 BulletTooltip）
• 使用不同的数据范围进行测试
• 通过键盘导航验证无障碍功能
• 在不同屏幕尺寸下测试响应式行为