syncfusion-blazor-bullet-chart

实现子弹图

NuGet： Syncfusion.Blazor.Charts + Syncfusion.Blazor.Themes（或单独的程序包 Syncfusion.Blazor.BulletChart） 命名空间： Syncfusion.Blazor.Charts

本指南全面介绍如何实现 Syncfusion Blazor 子弹图组件，用于 KPI 和绩效可视化。子弹图是一种专门用于在紧凑空间中展示关键绩效指标的条形图变体，可显示实际值、目标标记和定性范围。

何时使用此技能

在以下情况下，请立即使用此技能：

• 展示 KPI（关键绩效指标）仪表板
• 显示实际绩效与目标之间的对比
• 可视化包含定性范围（良好、一般、较差）的指标
• 为仪表板创建紧凑的绩效指标
• 跟踪销售目标、收入目标或配额完成情况
• 展示特征度量与比较度量
• 构建包含多个 KPI 指标的高管仪表板
• 在上下文区域中显示目标完成进度
• 将当前绩效与基准进行比较
• 在有限的仪表板空间中可视化绩效指标
• 为商业智能创建高密度数据可视化
• 以垂直或水平布局展示多个绩效指标
• 为 Blazor Server、WebAssembly 或 Web App 构建响应式 KPI 卡片或小组件

组件概述

Syncfusion Blazor 子弹图（SfBulletChart）是一种专为 KPI 可视化优化的专业图表组件。它提供：

• 实际条形（特征度量）：以水平或垂直条形显示主要数据值
• 目标条形（比较度量）：以垂直线或形状显示目标标记
• 定性范围：表示绩效级别（较差、满意、良好）的背景区域
• 紧凑设计：节省空间的布局，非常适合仪表板
• 多种布局：支持单个或多个子弹图，并按类别分组
• 自定义：提供丰富的样式、主题和格式选项

主要特性：

• 条形类型：Rect（默认）或 Dot，用于显示实际值
• 目标形状：Rect、Circle 或 Cross 标记
• 方向：水平（默认）或垂直布局
• 数据绑定：单个数据点、多个系列或基于类别的数据
• 交互功能：工具提示、数据标签、图例和事件
• 无障碍支持：符合 WCAG 标准，支持键盘导航

文档与导航指南

API 参考

SfBulletChart<TValue> 关键 API 概要——完整参考和示例请参阅 references/api-reference.md。

SfBulletChart — 关键参数

• DataSource： object — 数据集合（List、IEnumerable 或远程 DataManager）。
• ValueField： string — 实际值（特征值）的属性名称。
• TargetField： string — 目标值／比较值的属性名称。
• CategoryField： string — 类别分组的属性名称（显示多个子弹图时）。
• Minimum / Maximum / Interval： double — 坐标轴刻度配置。
• Orientation： OrientationType — Horizontal 或 Vertical。
• Type： FeatureType — 实际值条的渲染方式（Rect 或 Dot）。
• TargetTypes： List<TargetType> — 目标标记形状（例如 Rect、Circle、Cross）。
• Width / Height / Title / Theme： 用于控制布局和外观的视觉设置。

核心子组件

• BulletChartRange： 定义定性背景范围（End、Color、Opacity）。
• BulletChartRangeCollection： 多个 BulletChartRange 条目的容器。
• BulletChartDataLabel： 数据标签选项（Enable、Template、TextStyle）。
• BulletChartTooltip： 工具提示配置（Enable、Template、BulletChartTooltipTextStyle）。

外观与布局

• Border / Margin / MajorTickLines / MinorTickLines / CategoryLabelStyle： 坐标轴、刻度和间距控制。
• LegendSettings / LegendLocation / LegendTextStyle： 使用类别或多个子弹图时的图例外观。

事件

• Loaded / Resized： 生命周期事件，用于检测初始化和尺寸变化。
• TooltipRender / LabelRender / LegendRender / PointClick： 用于自定义运行时交互的钩子。

重要枚举

• OrientationType： Horizontal | Vertical。
• TargetType： Rect | Circle | Cross。
• FeatureType： Rect | Dot。

如需完整的 API 详情、方法签名、事件参数类和快速示例，请参阅 references/api-reference.md。

入门

📄 阅读： references/getting-started.md

从这里开始，了解安装、设置以及如何创建第一个子弹图。内容包括：

• 安装 Syncfusion.Blazor.BulletChart NuGet 包
• Blazor Server、WebAssembly 和 Web App 设置
• 服务注册和主题配置
• 使用示例数据实现基本的 SfBulletChart
• 项目结构和脚本引用
• 常见设置问题的故障排除

核心图表元素

实际值条和目标值条

📄 阅读： references/actual-target-bars.md

了解两种主要图表元素：

• 实际值条（特征值）： ValueField 映射、Rect 与 Dot 类型、样式设置
• 目标值条（比较值）： TargetField 映射、Circle/Cross/Rect 形状、多个目标值
• 自定义两种条的颜色
• 配置宽度和高度
• 视觉层级的最佳实践

定性范围

📄 阅读： references/ranges.md

配置用于定义性能区间的背景范围：

• 使用 End 属性设置范围边界
• 自定义颜色和不透明度
• 良好／满意／较差区间模式
• 多个范围配置
• 视觉设计最佳实践

数据配置

数据绑定

📄 阅读： references/data-binding.md

为子弹图配置数据源：

• 用于简单 KPI 的单个数据点
• 带类别的多个数据点（垂直布局）
• CategoryField、ValueField、TargetField 映射
• 本地数据源（List、Array、ExpandoObject）
• 使用 SfDataManager 进行远程数据绑定
• 动态数据更新和刷新模式

自定义与样式

坐标轴自定义

📄 阅读：references/axis-customization.md

自定义定量刻度：

• 最小值、最大值和间隔属性
• 水平或垂直方向
• 主刻度和次刻度配置
• 坐标轴标签格式和旋转
• 标签的相反位置
• RTL（从右到左）支持

视觉自定义

📄 阅读：references/visual-customization.md

控制外观、主题和布局：

• 图表尺寸（宽度、高度、容器）
• 主题选择（Material、Bootstrap、Fluent、Tailwind、Fabric、Highcontrast）
• 颜色调色板自定义
• 标题和副标题配置
• 边框、边距和内边距设置
• 响应式设计模式

其他功能

数据标签、工具提示和图例

📄 阅读：references/data-labels-tooltips-legend.md

增强数据的可见性和交互性：

• 数据标签：启用、设置格式和位置，以及配置模板
• 工具提示：默认和自定义模板、格式字符串
• 图例：位置、对齐方式、自定义文本、切换可见性

事件和无障碍功能

📄 阅读：references/events-accessibility.md

处理用户交互并确保无障碍访问：

• 事件：OnLoad、OnChartMouseClick、OnTooltipRender、OnLegendRender
• 无障碍功能：符合 WCAG 标准、键盘导航、屏幕阅读器、高对比度主题
• ARIA 属性和测试清单

快速入门示例

这是一个展示收入表现的简易子弹图：

@using Syncfusion.Blazor.Charts

<SfBulletChart DataSource="@RevenueData" 
               ValueField="ActualRevenue" 
               TargetField="TargetRevenue" 
               Minimum="0" 
               Maximum="300" 
               Interval="50" 
               Title="Revenue (in thousands)">
    <BulletChartRangeCollection>
        <BulletChartRange End="150" Color="#d32f2f"></BulletChartRange>
        <BulletChartRange End="250" Color="#ffa726"></BulletChartRange>
        <BulletChartRange End="300" Color="#66bb6a"></BulletChartRange>
    </BulletChartRangeCollection>
</SfBulletChart>

@code {
    public class RevenueMetric
    {
        public double ActualRevenue { get; set; }
        public double TargetRevenue { get; set; }
    }
    
    public List<RevenueMetric> RevenueData = new List<RevenueMetric>
    {
        new RevenueMetric { ActualRevenue = 270, TargetRevenue = 250 }
    };
}

此图表的内容：

• 表示 270K 美元收入的实际值条形
• 位于 250K 美元目标值处的目标标记
• 三个定性范围：差（0-150）、满意（150-250）、良好（250-300）
• 带标题的水平布局

常见用例

1. 包含多个指标的 KPI 仪表板

以垂直布局显示多个绩效指标：

@using Syncfusion.Blazor.Charts

<SfBulletChart DataSource="@PerformanceData" 
               CategoryField="Metric" 
               ValueField="Actual" 
               TargetField="Target" 
               Orientation="OrientationType.Vertical"
               Height="400"
               Minimum="0" 
               Maximum="100">
    <BulletChartRangeCollection>
        <BulletChartRange End="35" Color="#d32f2f"></BulletChartRange>
        <BulletChartRange End="70" Color="#ffa726"></BulletChartRange>
        <BulletChartRange End="100" Color="#66bb6a"></BulletChartRange>
    </BulletChartRangeCollection>
</SfBulletChart>

@code {
    public class KPIMetric
    {
        public string Metric { get; set; }
        public double Actual { get; set; }
        public double Target { get; set; }
    }
    
    public List<KPIMetric> PerformanceData = new List<KPIMetric>
    {
        new KPIMetric { Metric = "Revenue", Actual = 85, Target = 80 },
        new KPIMetric { Metric = "Profit", Actual = 65, Target = 75 },
        new KPIMetric { Metric = "Market Share", Actual = 45, Target = 60 },
        new KPIMetric { Metric = "Customer Satisfaction", Actual = 90, Target = 85 }
    };
}

2. 自定义样式的销售目标跟踪器

使用自定义颜色和目标标记跟踪销售业绩：

@using Syncfusion.Blazor.Charts
<SfBulletChart DataSource="@SalesData" 
               ValueField="Sales" 
               TargetField="Quota" 
               TargetTypes="new List<Syncfusion.Blazor.Charts.TargetType> { Syncfusion.Blazor.Charts.TargetType.Circle }"
               Type="FeatureType.Rect"
               Minimum="0" 
               Maximum="500" 
               Interval="100"
               Title="Q1 Sales Performance">
    <BulletChartRangeCollection>
        <BulletChartRange End="200" Color="#ff5252" Opacity="0.5"></BulletChartRange>
        <BulletChartRange End="350" Color="#ffeb3b" Opacity="0.5"></BulletChartRange>
        <BulletChartRange End="500" Color="#4caf50" Opacity="0.5"></BulletChartRange>
    </BulletChartRangeCollection>
    <BulletChartTooltip TValue="SalesMetric" Enable="true">
        <BulletChartTooltipTextStyle Color="white" FontWeight="600"></BulletChartTooltipTextStyle>
    </BulletChartTooltip>
</SfBulletChart>

@code {
    public class SalesMetric
    {
        public double Sales { get; set; }
        public double Quota { get; set; }
    }
    
    public List<SalesMetric> SalesData = new List<SalesMetric>
    {
        new SalesMetric { Sales = 380, Quota = 350 }
    };
}

3. 带数据标签的高管仪表板卡片

用于高管仪表板的紧凑型 KPI 卡片：

@using Syncfusion.Blazor.Charts

<div style="width: 300px; padding: 16px; border: 1px solid #e0e0e0; border-radius: 8px;">
    <SfBulletChart DataSource="@MetricData" 
                   ValueField="Value" 
                   TargetField="Goal" 
                   Minimum="0" 
                   Maximum="100" 
                   Interval="25"
                   Width="100%"
                   Height="60"
                   Title="Customer Retention Rate">
        <BulletChartRangeCollection>
            <BulletChartRange End="60" Color="#f44336"></BulletChartRange>
            <BulletChartRange End="80" Color="#ff9800"></BulletChartRange>
            <BulletChartRange End="100" Color="#4caf50"></BulletChartRange>
        </BulletChartRangeCollection>
        <BulletChartDataLabel>
            <BulletChartDataLabelStyle Color="#FFFFFF" Opacity="1" Size="15px" FontStyle="italic"></BulletChartDataLabelStyle>
        </BulletChartDataLabel>
    </SfBulletChart>
</div>

@code {
    public class Metric
    {
        public double Value { get; set; }
        public double Goal { get; set; }
    }
    
    public List<Metric> MetricData = new List<Metric>
    {
        new Metric { Value = 92, Goal = 85 }
    };
}

关键属性参考

必需属性

属性	类型	描述	默认值
DataSource	object	图表的数据集合	null
ValueField	string	实际值的属性名称	null
TargetField	string	目标值的属性名称	null
CategoryField	string	用于类别分组的属性	null
Minimum	double	刻度最小值	0
Maximum	double	刻度最大值	100
Interval	double	刻度间隔	10

视觉属性

属性	类型	描述	默认值
Type	FeatureType	实际值条形类型（Rect、Dot）	Rect
TargetTypes	List	目标标记形状	Rect
Orientation	OrientationType	布局方向	Horizontal
Width	string	图表宽度	"100%"
Height	string	图表高度	"126px"
Title	string	图表标题	""
Theme	ChartTheme	视觉主题	Material

数据显示

属性	类型	描述
BulletChartRangeCollection	Component	定性范围
BulletChartDataLabel	Component	数据标签配置
BulletChartTooltip	Component	工具提示设置
BulletChartLegend	Component	图例配置

实现工作流

实现子弹图时，请按以下顺序进行：

1. 从入门指南开始，了解安装和基本设置
2. 根据你的数据结构，通过数据绑定配置数据绑定
3. 使用范围设置范围，以定义性能区间
4. 从实际值和目标值条形添加实际值和目标值条形
5. 使用坐标轴自定义自定义坐标轴，以实现正确缩放
6. 应用视觉样式自定义
7. 使用数据标签、工具提示和图例增强图表
8. 使用事件和无障碍功能添加交互功能并满足无障碍要求

如有疑问或遇到问题，请参阅各参考文件中的故障排除部分，或查阅事件和无障碍功能了解合规要求。