SKILL.md
唯讀
名稱
syncfusion-react-sparkline
描述
實作 Syncfusion React Sparkline 組件以進行精簡的行內資料視覺化。適用於在有限空間中處理微型圖表(Sparkline)、迷你圖表或趨勢指示器。本 Skill 涵蓋全部 5 種 Sparkline 類型(Line、Column、Area、Win-loss、Pie)、工具提示(Tooltip)、標記(Marker)、資料標籤、範圍帶(Range band)、軸自訂以及主題。非常適合在不需要完整尺寸圖表的情況下,於 Grid、儀表板或表格內顯示資料趨勢。
實作 Syncfusion React Sparklines
本指南提供實作 Syncfusion React Sparkline 組件的完整說明。Sparkline 是一種輕量級、精簡的圖表,專為在極小空間內視覺化資料趨勢而設計,無需複雜的座標軸或座標系。
何時使用此 Skill
當您需要執行以下操作時,請使用此 Skill:
- 在儀表板或 Grid 中建立精簡的資料視覺化
- 與資料行內顯示趨勢指示器
- 實作佔用空間極小的迷你圖表
- 在表格儲存格或小型容器中顯示資料模式
- 建立 5 種 Sparkline 類型中的任何一種:Line、Column、Area、Win-Loss 或 Pie
- 為 Sparklines 新增工具提示、標記或資料標籤
- 使用主題和顏色自訂 Sparkline 外觀
- 實作具備無障礙存取與響應式的 Sparkline 視覺化
- 將 Sparklines 與 Grid 或其他組件整合
- 使用範圍帶突出顯示特定資料範圍
組件概述
Syncfusion React Sparkline 是一個高度壓縮的圖表組件,以簡單、精簡的格式呈現資料。主要功能包括:
- 5 種 Sparkline 類型: Line、Column、Area、Win-Loss 與 Pie
- 互動功能: 支援自訂與範本的工具提示(Tooltip)、追蹤線(Track line)
- 視覺標記(Marker): 突出顯示起點、終點、最高點、最低點和負值點
- 資料標籤(Data Label): 在特定點顯示帶有格式化的數值
- 範圍帶(Range Band): 沿 y 軸突出顯示特定的數值範圍
- 軸自訂: 支援 Numeric、Category 與 DateTime 數值類型
- 主題: Material、Fabric、Bootstrap 與 Highcontrast 主題
- 無障礙支援: 符合 WCAG 2.2、Section 508 標準並支援 WAI-ARIA
- Grid 整合: 專為在 Grid 儲存格內順暢運作而設計
- 在地化: 支援國際化多國語言
文檔與導覽指南
入門指南
📄 閱讀: references/getting-started.md
- 相依性與套件安裝(
@syncfusion/ej2-react-charts) - 使用 Vite 建立 React 應用程式
- 將 SparklineComponent 新增至專案
- 工具提示功能的模組注入(Module Injection)
- 使用 dataSource 屬性綁定資料源
- 變更 Sparkline 類型(Line, Column, Area, Win-Loss, Pie)
- 基本工具提示配置
- 第一個可運行的範例
Sparkline 類型
📄 閱讀: references/sparkline-types.md
- 所有 5 種 Sparkline 類型的概述
- Line 類型:連續趨勢視覺化
- Column 類型:離散數值比較
- Area 類型:填滿區域的趨勢視覺化
- Win-Loss 類型:二元結果表示(勝負圖)
- Pie 類型:比例資料顯示
- 基於資料與使用場景的類型選擇指南
- 每種類型的完整範例
外觀自訂
📄 閱讀: references/appearance-customization.md
- 使用 containerArea 配置 Sparkline 邊框
- 內距自訂(left, right, top, bottom)
- 容器背景顏色
- 主題選擇(Material, Fabric, Bootstrap, Highcontrast)
- 顏色與樣式最佳實踐
- 視覺設計指南
資料標籤
📄 閱讀: references/data-labels.md
- 為特定點啟用資料標籤
- 顯示選項:All、Start、End、High、Low、Negative
- 自訂填滿顏色、邊框、不透明度與文字樣式
- 使用 format 屬性格式化資料標籤文字
- 同時顯示 x 與 y 值
- 資料標籤定位與可讀性
標記(Markers)
📄 閱讀: references/markers.md
- 為 Sparkline 資料點新增標記
- 標記顯示選項:All、Start、End、High、Low、Negative
- 特殊點標記配置
- 自訂標記填滿、邊框、大小與不透明度
- 將標記與其他功能結合
- 標記使用的最佳實踐
使用者互動
📄 閱讀: references/user-interaction.md
- 工具提示配置與 SparklineTooltip 注入
- 工具提示自訂(填滿、文字樣式、格式、邊框)
- 使用 HTML 建立自訂工具提示範本
- 用於滑鼠追蹤的追蹤線功能
- 追蹤線顏色與樣式
- 互動功能最佳實踐
進階功能
📄 閱讀: references/advanced-features.md
- 使用 valueType 進行軸自訂(Numeric, Category, DateTime)
- 設定最小值/最大值(minX, maxX, minY, maxY)
- 軸線自訂(顏色、寬度、不透明度、dashArray)
- 用於突出顯示數值範圍的範圍帶
- 多重範圍帶配置
- 特殊點自訂(start, end, positive, negative, low)
- Win-Loss Sparkline 的平手點(Tie point)顏色
- Sparkline 尺寸(容器、像素、百分比尺寸設定)
- 在地化與文化語系支援
無障礙存取
📄 閱讀: references/accessibility.md
- WCAG 2.2 與 Section 508 合規性
- WAI-ARIA 屬性(img role, aria-label, aria-hidden)
- 鍵盤互動(Ctrl + P 用於列印)
- 螢幕閱讀器支援
- 由右至左(RTL)支援
- 色彩對比度指南
- 行動裝置支援
- 無障礙存取測試工具
API 參考
📄 閱讀: references/api-reference.md
SparklineComponent的完整 API 參考:props、events、methods、子指令,以及使用範例(基於官方 Syncfusion React Sparkline API)。
快速開始
安裝
npm install @syncfusion/ej2-react-charts --save
基本 Sparkline
import { SparklineComponent } from '@syncfusion/ej2-react-charts';
import * as React from 'react';
import * as ReactDOM from 'react-dom';
function App() {
const data = [0, 6, 4, 1, 3, 2, 5];
return (
<SparklineComponent
dataSource={data}
type="Line"
height="150px"
width="300px"
/>
);
}
export default App;
ReactDOM.render(<App />, document.getElementById('charts'));
帶有工具提示的 Sparkline
import { SparklineComponent, Inject, SparklineTooltip } from '@syncfusion/ej2-react-charts';
import * as React from 'react';
import * as ReactDOM from 'react-dom';
function App() {
const data = [0, 6, 4, 1, 3, 2, 5];
return (
<SparklineComponent
dataSource={data}
type="Area"
height="150px"
width="300px"
tooltipSettings={{ visible: true, format: '${x} : ${y}' }}
>
<Inject services={[SparklineTooltip]} />
</SparklineComponent>
);
}
export default App;
ReactDOM.render(<App />, document.getElementById('charts'));
常見模式
帶有標記的 Column Sparkline
import { SparklineComponent } from '@syncfusion/ej2-react-charts';
import * as React from 'react';
import * as ReactDOM from 'react-dom';
function ColumnSparkline() {
const data = [3, 6, 4, 1, 3, 2, 5];
return (
<SparklineComponent
dataSource={data}
type="Column"
height="150px"
width="300px"
markerSettings={{ visible: ['High', 'Low'] }}
highPointColor="green"
lowPointColor="red"
/>
);
}
export default ColumnSparkline;
ReactDOM.render(<ColumnSparkline />, document.getElementById('charts'));
Win-Loss Sparkline
import { SparklineComponent } from '@syncfusion/ej2-react-charts';
import * as React from 'react';
import * as ReactDOM from 'react-dom';
function WinLossSparkline() {
const data = [12, 15, -10, 13, 15, 6, -12, 17, 13, 0, 8, -10];
return (
<SparklineComponent
dataSource={data}
type="WinLoss"
height="150px"
width="300px"
tiePointColor="blue"
/>
);
}
export default WinLossSparkline;
ReactDOM.render(<WinLossSparkline />, document.getElementById('charts'));
帶有資料標籤的 Sparkline
import { SparklineComponent } from '@syncfusion/ej2-react-charts';
import * as React from 'react';
import * as ReactDOM from 'react-dom';
function SparklineWithLabels() {
const data = [0, 6, 4, 1, 3, 2, 5];
return (
<SparklineComponent
dataSource={data}
type="Line"
height="150px"
width="300px"
dataLabelSettings={{
visible: ['Start', 'End'],
border: { color: 'blue', width: 1 },
fill: 'blue',
opacity: 0.4,
textStyle: { color: 'white' }
}}
/>
);
}
export default SparklineWithLabels;
ReactDOM.render(<SparklineWithLabels />, document.getElementById('charts'));
帶有範圍帶的 Sparkline
import { SparklineComponent } from '@syncfusion/ej2-react-charts';
import * as React from 'react';
import * as ReactDOM from 'react-dom';
function SparklineWithRangeBand() {
const data = [0, 6, 4, 1, 3, 2, 5];
return (
<SparklineComponent
dataSource={data}
type="Area"
height="150px"
width="300px"
rangeBandSettings={[
{ startRange: 1, endRange: 3, color: '#bfd4fc', opacity: 0.4 }
]}
/>
);
}
export default SparklineWithRangeBand;
ReactDOM.render(<SparklineWithRangeBand />, document.getElementById('charts'));
重要 Props 參考
| 屬性 | 類型 | 說明 |
|---|---|---|
dataSource |
object[] | Sparkline 的資料源 |
type |
string | Sparkline 類型:'Line', 'Column', 'Area', 'WinLoss', 'Pie' |
xName |
string | 來自 dataSource 的 x 軸屬性名稱 |
yName |
string | 來自 dataSource 的 y 軸屬性名稱 |
height |
string | Sparkline 的高度 |
width |
string | Sparkline 的寬度 |
fill |
string | Sparkline 的顏色 |
valueType |
string | 軸數值類型:'Numeric', 'Category', 'DateTime' |
markerSettings |
object | 標記的配置 |
dataLabelSettings |
object | 資料標籤的配置 |
tooltipSettings |
object | 工具提示的配置 |
axisSettings |
object | 軸的最小值/最大值與軸線自訂 |
rangeBandSettings |
object[] | 範圍帶配置 |
theme |
string | 主題:'Material', 'Fabric', 'Bootstrap', 'Highcontrast' |
padding |
object | Sparkline 周圍的內距(left, right, top, bottom) |
containerArea |
object | Sparkline 區域的邊框與背景 |
常見使用場景
- 儀表板趨勢指示器: 與指標行內顯示 KPI 趨勢
- Grid 整合: 在表格儲存格中顯示迷你圖表
- 財務資料: 用於股票市場漲跌的 Win-Loss Sparklines
- 效能監控: 伺服器指標或回應時間的快速視覺化
- 比較檢視: 並排多個 Sparklines 以進行資料比較
- 行動裝置儀表板: 小螢幕的精簡視覺化
- 電子郵件報告: 可快速渲染的輕量級圖表
- 即時監控: 簡單、快速更新的視覺化
後續步驟
- 從入門指南開始: 閱讀
references/getting-started.md以進行安裝與基本設定 - 選擇您的類型: 閱讀
references/sparkline-types.md以選擇合適的 Sparkline 類型 - 自訂外觀: 閱讀
references/appearance-customization.md以瞭解樣式設定 - 新增互動性: 閱讀
references/user-interaction.md以設定工具提示與追蹤線 - 進階配置: 閱讀
references/advanced-features.md以瞭解座標軸、範圍帶等進階設定






