syncfusion-react-bullet-chart

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Bullet Charts

实现Syncfusion React Bullet Chart组件

A skill for implementing and customizing Syncfusion's React Bullet Chart component. Bullet charts are compact data visualization components designed to compare a primary measure (actual value) against a target measure within qualitative ranges.

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

When to Use This Skill

何时使用本技能

Use this skill when users need to:

Display performance metrics or KPIs with target comparisons
Create compact data visualizations showing actual vs. target values
Visualize progress against goals with qualitative ranges (poor/good/excellent)
Build dashboards with space-efficient performance indicators
Show feature measures (actual bars) compared to comparative measures (target bars)
Implement horizontal or vertical bullet charts
Display multiple metrics in a compact layout
Create accessible, keyboard-navigable chart visualizations

当用户需要以下功能时使用本技能：

展示带有目标对比的绩效指标或KPI
创建展示实际值与目标值的紧凑数据可视化图表
使用定性范围（差/良/优）可视化目标完成进度
构建空间高效的绩效指标仪表盘
展示特征度量值（实际条）与对比度量值（目标条）的对比
实现水平或垂直方向的Bullet Chart
在紧凑布局中展示多个指标
创建支持键盘导航的可访问图表可视化

Component Overview

组件概述

The Bullet Chart consists of:

Value Bar (Feature Measure): The primary data/actual value being measured
Comparative Bar (Target Marker): The target or comparison value
Qualitative Ranges: Background bands indicating performance levels (e.g., poor, satisfactory, good)
Quantitative Scale: The axis showing numerical measurements
Title/Subtitle: Descriptive text for the chart

Bullet Chart包含以下部分：

值条（特征度量值）：被测量的主要数据/实际值
对比条（目标标记）：目标或对比值
定性范围：表示绩效水平的背景条带（如差、满意、优）
定量刻度：显示数值度量的坐标轴
标题/副标题：图表的描述性文本

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

📄 阅读： references/getting-started.md

API Reference

API参考

📄 Read: references/api.md

Summarizes
```
BulletChartComponent
```
props, methods, events and directives used across examples

📄 阅读： references/api.md

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

Data Binding

数据绑定

📄 Read: references/data-binding.md

📄 阅读： references/data-binding.md

Value Bar Configuration

值条配置

📄 Read: references/value-bar.md

Value bar (Feature Measure) overview and purpose
Mapping valueField from data source
Types of actual bar shapes (Rect, Dot)
Changing bar type with type property
Border customization using valueBorder (color, width)
Fill color customization using valueFill
Height customization using valueHeight
Binding colors dynamically from dataSource
Complete examples for each customization option

📄 阅读： references/value-bar.md

值条（特征度量值）概述与用途
从数据源映射valueField
实际条的形状类型（矩形、圆点）
使用type属性更改条类型
使用valueBorder自定义边框（颜色、宽度）
使用valueFill自定义填充颜色
使用valueHeight自定义高度
从数据源动态绑定颜色
每个自定义选项的完整示例

Comparative Bar Configuration

对比条配置

📄 Read: references/comparative-bar.md

Comparative bar (Target Measure) overview
Mapping targetField from data source
Types of target bar shapes (Circle, Cross, Rect)
Changing target type with targetTypes property
Customizing target appearance with targetColor
Adjusting target width with targetWidth property
Binding target colors from dataSource
Complete examples for each target type

📄 阅读： references/comparative-bar.md

对比条（目标度量值）概述
从数据源映射targetField
目标条的形状类型（圆形、十字形、矩形）
使用targetTypes属性更改目标类型
使用targetColor自定义目标外观
使用targetWidth属性调整目标宽度
从数据源绑定目标颜色
每种目标类型的完整示例

Ranges Configuration

范围配置

📄 Read: references/ranges.md

Ranges representing qualitative bands (Good, Bad, Satisfactory)
Using BulletRangeCollectionDirective and BulletRangeDirective
Setting range boundaries with end property
Understanding minimum value as range starting point
Configuring multiple ranges for different quality levels
Color customization with color property
Opacity adjustment with opacity property
Complete examples with multiple colored ranges

📄 阅读： references/ranges.md

表示定性区间（优、差、满意）的范围
使用BulletRangeCollectionDirective和BulletRangeDirective
使用end属性设置范围边界
理解最小值作为范围起始点
为不同质量级别配置多个范围
使用color属性自定义颜色
使用opacity属性调整透明度
带有多个彩色范围的完整示例

Titles and Subtitles

标题与副标题

📄 Read: references/titles.md

Adding chart title with title property
Adding subtitle for additional information
Title positioning with titlePosition property (Left, Right, Top, Bottom)
Default position (Top) behavior
Title style customization with titleStyle (color, opacity, font properties)
Subtitle style customization with subtitleStyle (color, opacity, font properties)
Complete examples for each position
Font customization examples (size, family, weight, style)

📄 阅读： references/titles.md

使用title属性添加图表标题
添加副标题以提供额外信息
使用titlePosition属性设置标题位置（左、右、上、下）
默认位置（顶部）的行为
使用titleStyle自定义标题样式（颜色、透明度、字体属性）
使用subtitleStyle自定义副标题样式（颜色、透明度、字体属性）
每个位置的完整示例
字体自定义示例（大小、字体族、字重、样式）

Tooltips

工具提示

📄 Read: references/tooltips.md

Default tooltip behavior (hidden by default)
Enabling tooltips with tooltip.enable property
Injecting BulletTooltip module into services
Displaying actual and target values on hover
Creating custom templates with template property
Using ${target} and ${value} placeholders in templates
Tooltip appearance customization (fill, border, textStyle)
Font customization for tooltip text
Complete examples for default and custom tooltips

📄 阅读： references/tooltips.md

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

Data Labels

数据标签

📄 Read: references/data-labels.md

Data labels for identifying actual bar values
Enabling data labels with dataLabel.enable property
Label display behavior and positioning
Style customization with labelStyle property
Font properties (size, family, weight, style)
Color and opacity adjustments
Complete examples with styled data labels

📄 阅读： references/data-labels.md

用于标识实际条值的数据标签
使用dataLabel.enable属性启用数据标签
标签显示行为与位置
使用labelStyle属性自定义样式
字体属性（大小、字体族、字重、样式）
颜色和透明度调整
带有样式化数据标签的完整示例

Axis Customization

轴自定义

📄 Read: references/axis-customization.md

MajorTickLines customization (width, height, color, useRangeColor)
MinorTickLines customization (width, height, color, useRangeColor)
Tick placement with tickPosition (Inside, Outside)
Label formatting with labelFormat (globalize formats: n1, n2, p1, c1, etc.)
Format table showing common number, percentage, and currency formats
Group separator for thousands with enableGroupSeparator
Custom label format with ${value} placeholder
Label placement with labelPosition (Inside, Outside)
Opposed position with opposedPosition property
Category labels with categoryField for X-axis
Category label styling with categoryLabelStyle and labelStyle
useRangeColor for labels matching range colors
Complete examples for each axis feature

📄 阅读： references/axis-customization.md

主刻度线自定义（宽度、高度、颜色、useRangeColor）
次刻度线自定义（宽度、高度、颜色、useRangeColor）
使用tickPosition设置刻度位置（内部、外部）
使用labelFormat设置标签格式（全球化格式：n1、n2、p1、c1等）
显示常用数字、百分比和货币格式的格式表
使用enableGroupSeparator添加千位分隔符
使用${value}占位符自定义标签格式
使用labelPosition设置标签位置（内部、外部）
使用opposedPosition属性设置反向位置
使用categoryField设置X轴的类别标签
使用categoryLabelStyle和labelStyle自定义类别标签样式
useRangeColor使标签颜色与范围颜色匹配
每个轴功能的完整示例

Chart Dimensions

图表尺寸

📄 Read: references/dimensions.md

Container size configuration with inline styles and CSS
Setting chart dimensions with width and height properties
Pixel sizing for fixed dimensions
Percentage sizing for responsive behavior relative to container
Default size behavior (126px height, window width)
Complete examples for container and direct sizing

📄 阅读： references/dimensions.md

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

Customization Options

自定义选项

📄 Read: references/customization.md

Orientation with orientation property (Horizontal, Vertical)
Default Horizontal orientation
Right-to-left (RTL) support with enableRtl property
Animation configuration with animation property (duration, delay)
Linear animation for actual and target bars
Theme support with theme property
Available Syncfusion themes
Complete examples for each customization

📄 阅读： references/customization.md

使用orientation属性设置方向（水平、垂直）
默认水平方向
使用enableRtl属性支持从右到左（RTL）渲染
使用animation属性配置动画（时长、延迟）
实际条和目标条的线性动画
使用theme属性应用主题
可用的Syncfusion主题
每个自定义选项的完整示例

Accessibility

可访问性

📄 Read: references/accessibility.md

Accessibility compliance (ADA, Section 508, WCAG 2.2)
Accessibility features table with compatibility status
WAI-ARIA attributes and patterns (img role, button role, aria-label, aria-pressed)
Keyboard interaction support (Tab, Shift+Tab, Ctrl+P)
Screen reader support
Right-to-left (RTL) support for internationalization
Color contrast compliance
Mobile device support
Testing with accessibility-checker and axe-core tools
Sample accessibility demo reference

📄 阅读： references/accessibility.md

可访问性合规性（ADA、Section 508、WCAG 2.2）
带有兼容性状态的可访问性功能表
WAI-ARIA属性和模式（img角色、button角色、aria-label、aria-pressed）
键盘交互支持（Tab、Shift+Tab、Ctrl+P）
屏幕阅读器支持
国际化的从右到左（RTL）支持
颜色对比度合规性
移动设备支持
使用accessibility-checker和axe-core工具进行测试
示例可访问性演示参考

Quick Start Example

快速入门示例

tsx

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>
  );
}

tsx

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>
  );
}

Common Patterns

常见模式

Performance Dashboard with Multiple Metrics

多指标绩效仪表盘

Display multiple bullet charts vertically to show various KPIs:

tsx

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

垂直显示多个Bullet Chart以展示各类KPI：

tsx

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

// 使用categoryField将每个指标映射到单独的BulletChartComponent

Dynamic Color from Data

从数据源动态获取颜色

Bind colors directly from your data source:

tsx

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

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

直接从数据源绑定颜色：

tsx

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

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

Custom Tooltip Template

自定义工具提示模板

Show formatted values with custom HTML:

tsx

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

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

tsx

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

Responsive Layout

响应式布局

Use percentage-based sizing for responsive dashboards:

tsx

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

使用百分比尺寸构建响应式仪表盘：

tsx

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

Key Props

关键属性

Property	Type	Purpose
`dataSource`	Array	Data collection for the chart
`valueField`	string	Field name for actual/feature measure
`targetField`	string	Field name for target/comparative measure
`minimum`	number	Minimum value of quantitative scale
`maximum`	number	Maximum value of quantitative scale
`interval`	number	Interval between axis labels
`title`	string	Chart title text
`subtitle`	string	Chart subtitle text
`type`	string	Value bar shape: 'Rect' or 'Dot'
`targetTypes`	string[]	Target bar shapes: 'Circle', 'Cross', 'Rect'
`orientation`	string	Chart orientation: 'Horizontal' or 'Vertical'
`width`	string	Chart width (pixels or percentage)
`height`	string	Chart height (pixels or percentage)
`enableRtl`	boolean	Enable right-to-left rendering
`theme`	string	Apply Syncfusion theme
`tooltip`	object	Tooltip configuration with enable, template, fill, border, textStyle
`dataLabel`	object	Data label configuration with enable, labelStyle

属性	类型	用途
`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

Common Use Cases

常见使用场景

KPI Dashboard

KPI仪表盘

Use bullet charts to display multiple performance indicators:

Set different targets for each metric
Use red/yellow/green ranges for performance levels
Add category labels for metric names
Enable tooltips for detailed information

使用Bullet Chart展示多个绩效指标：

为每个指标设置不同的目标
使用红/黄/绿范围表示绩效水平
添加类别标签标识指标名称
启用工具提示展示详细信息

Sales Performance Tracker

销售绩效跟踪器

Compare actual sales against targets:

Map revenue data to valueField
Set quarterly/monthly targets in targetField
Configure ranges for underperforming/meeting/exceeding targets
Use data labels to show exact values

对比实际销售额与目标值：

将收入数据映射到valueField
在targetField中设置季度/月度目标
配置范围表示未达标/达标/超额达标
使用数据标签显示精确值

Progress Indicators

进度指示器

Show progress toward goals with visual context:

Use percentage-based ranges (0-50%, 50-75%, 75-100%)
Customize colors to match brand guidelines
Add animations for engaging transitions
Position titles on the left for compact layout

通过视觉上下文展示目标完成进度：

使用百分比范围（0-50%、50-75%、75-100%）
自定义颜色以匹配品牌指南
添加动画实现吸引人的过渡效果
将标题放置在左侧以实现紧凑布局

Comparative Analysis

对比分析

Compare multiple items side-by-side:

Use vertical orientation for space efficiency
Set consistent scale across all charts
Apply category labels for clear identification
Customize target types (Circle, Cross) for distinction

并排对比多个项目：

使用垂直方向节省空间
为所有图表设置统一刻度
添加类别标签以便清晰识别
自定义目标类型（圆形、十字形）以区分

Mobile Dashboards

移动仪表盘

Create responsive, touch-friendly visualizations:

Use percentage-based dimensions
Increase touch target sizes for bars
Enable mobile-optimized tooltips
Test with accessibility tools for screen readers

创建响应式、触控友好的可视化图表：

使用百分比尺寸
增大条的触控目标大小
启用针对移动设备优化的工具提示
使用屏幕阅读器的可访问性工具进行测试

Edge Cases and Troubleshooting

边缘情况与故障排除

Data not displaying:

Verify valueField and targetField match data source property names
Check that dataSource is an array with valid objects
Ensure minimum/maximum encompass your data range

Ranges not visible:

Import BulletRangeCollectionDirective and BulletRangeDirective from @syncfusion/ej2-react-charts
Set end values in ascending order
Verify end values are within minimum/maximum bounds

Tooltips not working:

Inject BulletTooltip module:
```
<Inject services={[BulletTooltip]} />
```
Set tooltip.enable to true
Check that tooltip object is properly configured

Title/subtitle overlapping:

Adjust titlePosition to Left, Right, Top, or Bottom
Increase chart dimensions (width/height)
Customize titleStyle and subtitleStyle font sizes

Axis labels cut off:

Increase chart width or height
Adjust label format to shorter notation (e.g., 'n1' instead of full numbers)
Use enableGroupSeparator for better readability

数据未显示：

验证valueField和targetField与数据源属性名匹配
检查dataSource是否为包含有效对象的数组
确保minimum/maximum包含数据范围

范围不可见：

从@syncfusion/ej2-react-charts导入BulletRangeCollectionDirective和BulletRangeDirective
按升序设置end值
验证end值在minimum/maximum范围内

工具提示不工作：

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

标题/副标题重叠：

将titlePosition调整为左、右、上或下
增大图表尺寸（width/height）
自定义titleStyle和subtitleStyle的字体大小

轴标签被截断：

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