syncfusion-angular-sparkline

实现 Syncfusion Angular Sparkline 组件

何时使用此技能

在以下情况下使用此技能：

• 可视化紧凑数据 - 在表格、网格或仪表板中以内嵌方式显示小型时间序列数据集
• 添加迷你图表 - 呈现折线、柱形、面积、饼图或盈亏迷你图
• 增强数据展示效果 - 为关键点（最高点、最低点、起点、终点、负值）添加标记
• 内嵌显示指标 - 在迷你图中显示数据标签和工具提示
• 自定义外观 - 应用主题、样式、无障碍功能或范围带
• 集成到现有应用 - 设置 Sparkline 模块并正确注入服务
• 从旧版迁移 - 从 EJ1 Sparkline 迁移到 EJ2 Angular Sparkline

组件概述

Syncfusion Angular Sparkline 是一款轻量级数据可视化组件，可在狭小空间内显示紧凑的图表。迷你图适用于：

• 表格或仪表板中的趋势指标
• 序列数据的可视化呈现
• 内嵌显示随时间变化的性能或指标

主要特点：

• 紧凑呈现 - 可放入网格单元格或内嵌指标中
• 多种类型 - 折线、柱形、面积、饼图、盈亏可视化
• 交互功能 - 工具提示、标记、数据标签
• 可自定义 - 标记、颜色、坐标轴设置、主题
• 无障碍 - 支持 WCAG、键盘导航和 RTL

⚠️ 重要：多个迷你图必须使用唯一 ID

在同一页面上使用多个迷你图组件时，必须为每个迷你图设置唯一的 id 属性，以确保正确呈现。

<ejs-sparkline id="sparkline1" [dataSource]="data1"></ejs-sparkline>
<ejs-sparkline id="sparkline2" [dataSource]="data2"></ejs-sparkline>
<ejs-sparkline id="sparkline3" [dataSource]="data3"></ejs-sparkline>


<ejs-sparkline [dataSource]="data1"></ejs-sparkline>
<ejs-sparkline [dataSource]="data2"></ejs-sparkline>

如果没有唯一 ID，迷你图可能会：

• 完全无法呈现
• 呈现错误的数据
• 相互重叠或冲突
• 显示不一致的样式

文档和导航指南

本技能将指导你实现迷你图。以下是主要主题：

入门

📄 阅读： references/getting-started.md

• Angular 19+ 的安装和软件包设置
• 基本的迷你图组件实现
• 注入 SparklineTooltipService 模块
• 使用 dataSource、xName 和 yName 绑定数据
• 启用工具提示并运行应用
• 何时阅读：实现第一个迷你图之前

迷你图类型

📄 阅读： references/sparkline-types.md

• 折线类型（默认，用于折线图可视化）
• 柱形类型（垂直柱形表示）
• 面积类型（填充区域图表）
• 饼图类型（比例/构成数据）
• 盈亏类型（二元结果：成功/失败）
• 类型比较和选择标准
• 何时阅读：选择最适合表示数据的迷你图类型

标记

📄 阅读： references/markers.md

• 为所有点或特定点启用标记
• 标记选项：全部、起点、终点、最高点、最低点、负值
• 自定义标记外观（填充、边框、大小、不透明度）
• 组合多种标记类型
• 何时阅读：突出显示关键数据点（峰值、谷值、起点/终点）

数据标签

📄 阅读： references/data-labels.md

• 为特定点启用数据标签
• 标签选项：全部、起点、终点、最高点、最低点、负值
• 自定义标签样式（填充、边框、文本颜色）
• 使用自定义格式设置标签文本
• 在标签中显示 x 和 y 值
• 何时阅读：在迷你图上直接添加数值或格式化后的值

高级功能

📄 阅读： references/advanced-features.md

• 区间带可视化（阴影背景区域）
• 坐标轴自定义（最小值、最大值、间隔设置）
• 用户交互（工具提示配置、事件处理）
• 特殊数据点自定义（最高点／最低点颜色）
• 容器尺寸和响应式尺寸
• RTL（从右向左）支持
• 阅读时机：实现区间带、坐标轴控制或事件等复杂功能时

外观与无障碍

📄 阅读： references/appearance-and-accessibility.md

• CSS 主题和主题切换
• 使用 CSS 类自定义外观
• 本地化（特定区域设置的格式）
• 符合 WCAG 无障碍标准
• 支持键盘导航
• 适配不同屏幕尺寸的响应式设计
• 阅读时机：为 sparkline 设置样式、支持多种区域设置或确保无障碍体验时

迁移指南

📄 阅读： references/migration-guide.md

• 从 EJ1 Sparkline 迁移到 EJ2
• API 属性映射和变更
• 破坏性变更和已弃用功能
• 查找旧版功能的等效实现
• 阅读时机：从较旧的 Syncfusion 版本升级时

快速入门示例

以下是渲染基本 sparkline 的最简示例：

import { SparklineModule } from '@syncfusion/ej2-angular-charts'
import { Component } from '@angular/core';

@Component({
  imports: [SparklineModule],
  standalone: true,
  selector: 'app-container',
  template: `<ejs-sparkline 
    id='sparkline-container'
    [dataSource]="data"
    xName="x"
    yName="y"
    type="Line">
  </ejs-sparkline>`
})
export class AppComponent {
  data = [
    { x: 'Jan', y: 2 },
    { x: 'Feb', y: 6 },
    { x: 'Mar', y: 4 },
    { x: 'Apr', y: 8 },
    { x: 'May', y: 5 }
  ]
}

输出： 一个简单的折线 sparkline，显示各月份的趋势。

常见模式

模式 1：表格单元格中的 Sparkline

在网格或表格中嵌入 sparkline，以显示每行的趋势：

<table>
  <tr>
    <td>Product A</td>
    <td><ejs-sparkline [dataSource]="salesA" type="Column" height="50px" width="150px"></ejs-sparkline></td>
  </tr>
  <tr>
    <td>Product B</td>
    <td><ejs-sparkline [dataSource]="salesB" type="Column" height="50px" width="150px"></ejs-sparkline></td>
  </tr>
</table>

模式 2：使用标记突出显示关键数据点

在最高点和最低点显示标记，以突出性能峰值：

@Component({
  template: `<ejs-sparkline 
    [dataSource]="data"
    type="Line"
    [markerSettings]="markerSettings">
  </ejs-sparkline>`
})
export class HighlightComponent {
  data = [10, 25, 15, 35, 20, 30]
  markerSettings = {
    visible: ['High', 'Low'],
    fill: '#FF5733',
    size: 8,
    opacity: 1
  }
}

模式 3：添加详细信息工具提示

启用工具提示，以便悬停时显示精确值，并使用自定义格式：

import { SparklineModule, SparklineTooltipService } from '@syncfusion/ej2-angular-charts'

@Component({
  imports: [SparklineModule],
  standalone: true,
  providers: [SparklineTooltipService],
  template: `<ejs-sparkline 
    [dataSource]="data"
    xName="month"
    yName="sales"
    [tooltipSettings]="tooltipSettings">
  </ejs-sparkline>`
})
export class TooltipComponent {
  data = [
    { month: 'Jan', sales: 10000 },
    { month: 'Feb', sales: 15000 }
  ]
  tooltipSettings = { 
    visible: true,
    format: '${month}: ${sales} units'
  }
}

模式 4：用于阈值的区间带

显示阴影区域，以标示可接受的性能范围：

@Component({
  template: `<ejs-sparkline 
    [dataSource]="data"
    type="Area"
    [rangeBandSettings]="rangeBandSettings">
  </ejs-sparkline>`
})
export class RangeBandComponent {
  data = [20, 30, 25, 35, 28, 32, 40]
  rangeBandSettings = [
    { startRange: 25, endRange: 35, color: '#90EE90', opacity: 0.3 },  // Good range
    { startRange: 15, endRange: 25, color: '#FFD700', opacity: 0.3 }   // Warning range
  ]
}

模式 5：事件处理

处理 sparkline 事件以响应用户交互：

@Component({
  template: `<ejs-sparkline 
    [dataSource]="data"
    (pointRegionMouseClick)="onPointClick($event)"
    (sparklineMouseClick)="onSparklineClick($event)">
  </ejs-sparkline>`
})
export class EventComponent {
  data = [10, 25, 15, 35, 20]
  
  onPointClick(args: any) {
    console.log('Point clicked:', args.pointIndex, args.value)
  }
  
  onSparklineClick(args: any) {
    console.log('Sparkline clicked')
  }
}

关键属性

属性	类型	默认值	用途
dataSource	Array	[]	数据数组（原始值或对象）——将数据绑定到迷你图
xName	string	-	X 值对应的对象属性名（例如，'month'、'date'）
yName	string	-	Y 值对应的对象属性名（例如，'sales'、'count'）
type	string	'Line'	迷你图类型：Line、Column、Area、Pie、WinLoss
markerSettings	object	-	配置标记的显示和样式（High、Low、Start、End、Negative、All），包括填充、边框、大小和不透明度属性
dataLabelSettings	object	-	配置数据标签的显示，包括 visible 数组、格式字符串、填充颜色、边框、textStyle 和 edgeLabelMode
tooltipSettings	object	-	工具提示配置（visible、带有 ${x}/${y} 占位符的格式、填充、边框、textStyle、trackLineSettings）
height	string/number	'100px'	容器高度，单位为 px（例如，'150px'）或百分比（例如，'100%'）
width	string/number	'100%'	容器宽度，单位为 px（例如，'300px'）或百分比（例如，'100%'）
rangeBandSettings	object/array	-	配置背景着色区域（startRange、endRange、color、opacity）——支持单个对象或用于多个区域的数组
axisSettings	object	-	轴配置（minX、maxX、minY、maxY、intervalX、intervalY、valueType：Numeric/Category/DateTime）
highPointColor	string	-	数据系列中最高点的颜色（十六进制颜色值或颜色名称）
lowPointColor	string	-	数据系列中最低点的颜色（十六进制颜色值或颜色名称）
startPointColor	string	-	系列中第一个点/起始点的颜色
endPointColor	string	-	系列中最后一个点/终止点的颜色
negativePointColor	string	-	负数据值（小于零）的颜色
fill	string	-	迷你图区域/列/条形的填充颜色（主要系列颜色）
lineWidth	number	1	线型迷你图的线条粗细（建议范围为 1-10）
opacity	number	1	迷你图系列的不透明度（范围为 0-1）
enableRtl	boolean	false	为从右向左书写的语言（阿拉伯语、希伯来语）启用从右向左布局
valueType	string	'Numeric'	轴值的数据类型：Numeric、Category、DateTime
format	string	-	轴值的数字格式（例如，'n2' 表示保留 2 位小数，'c' 表示货币）
useGroupingSeparator	boolean	false	启用千位分隔符格式（例如，1,000）
theme	string	'Material'	视觉主题：Material、Fabric、Bootstrap、HighContrast 等
border	object	-	迷你图容器的边框配置（color、width）
containerArea	object	-	容器自定义设置（背景颜色、边框设置）
padding	object	-	迷你图的内边距（左、右、上、下，单位为像素）

常见用例

1. 仪表板指标 - 在实时仪表板和指标视图中显示迷你图表，实时展示 KPI 趋势。非常适合在紧凑的网格布局中显示多个指标的高管仪表板。

2. 财务数据可视化 - 使用范围带可视化股票价格、交易量或货币趋势，以标示支撑位／阻力位区域。使用标记突出显示重要价格点，并通过工具提示展示详细数值。

3. 性能监控 - 展示在 24 小时内监控的系统指标（CPU、内存、磁盘使用量、网络吞吐量）。使用颜色区分负向峰值，并通过范围带显示可接受的运行范围。

4. 数据表集成 - 在数据网格单元格中嵌入迷你图表，以便在表格行中比较多个产品、用户或区域的性能趋势。每行均显示自己的迷你趋势图。

5. 胜负分析 - 使用 WinLoss 类型，以紧凑的二元格式跟踪成功／失败结果（通过／失败、批准／拒绝、胜利／失败）。非常适合游戏结果、测试结果或审批工作流。

6. 时间序列精简视图 - 以精简格式显示历史数据和趋势图。展示每周、每月或每年的模式，同时不占用太多屏幕空间。

7. 销售渠道跟踪 - 按产品类别或销售区域展示月度／季度销售趋势。使用不同的迷你图类型表示不同的指标（收入使用 Area，销量使用 Column）。

8. 用户活动分析 - 跟踪特定时间段内的互动指标（页面访问量、活跃用户数、会话时长）。使用标记突出显示，以识别模式和异常。

9. 质量指标仪表板 - 展示各生产批次的缺陷率、正常运行时间百分比或质量评分。使用范围带显示可接受的质量区间，并通过标记标出异常值。

10. 资源利用率监控 - 一目了然地监控带宽消耗、存储容量趋势或许可证使用模式。设置坐标轴边界以显示容量上限，并使用颜色区分超出阈值的点。

11. IoT 传感器数据 - 在 IoT 监控仪表板的紧凑图表中显示实时传感器读数（温度、湿度、压力）。以最小的空间展示每个传感器的 24 小时趋势。

12. 社交媒体分析 - 跟踪粉丝增长、互动率或帖子覆盖量随时间的变化。使用 Pie 迷你图展示不同平台上的互动占比。

---

后续步骤： 从 getting-started.md 开始，安装并渲染你的第一个迷你图，然后根据需要查看其他参考指南。

API 参考

references 文件夹中提供了 Syncfusion Angular Sparkline 的精简 API 参考，其中包含属性锚点、方法链接，以及映射到官方文档的事件参数类型。

阅读 API 参考：references/api-reference.md