PatternsData Display
DonutChart
@mox-hub/patterns 模式 · Data Display · canonical
donut-chart@mox-hub/patternsData Displaycanonicalsrc/components/donut-chart.tsx变体轴
sizesmmd
变体演示donut-chart
待办825%
进行中39.4%
已完成2165.6%
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| items* | DonutChartItem[] | — | — |
| total* | ReactNode | — | — |
| totalLabel* | ReactNode | — | — |
| formatValue* | (value: number) => string | — | — |
| legend* | boolean | true | — |
| legendColumns* | 1 | 2 | 3 | 2 | — |
| size* | "sm" | "md" | "md" | — |
| empty* | ReactNode | — | — |
| ariaLabel* | string | — | — |
| otherLabel* | ReactNode | DONUT_DEFAULT_LABELS.other | — |
源码
import type { ReactNode } from "react"
import { Pie, PieChart } from "recharts"
import { ChartLegendGrid, seriesColor } from "./chart-legend-grid"
import {
ChartContainer,
ChartTooltip,
ChartTooltipContent,
type ChartConfig,
} from "./chart"
import { useFormatters, useMessages } from "@mox-hub/ui/i18n"
import { cn } from "@mox-hub/ui"
/**
* DonutChart —— 环形占比图(语义层,2026-10-11 图表重设计批)
*
* 「细环 donut + 中心总计 + 图例网格」一体件:ChartContainer + recharts PieChart
* (ui/chart 唯一封装,§17.1),环心 absolute 叠放总计数值,右侧(或下方随布局)
* ChartLegendGrid。色序走 SERIES_COLORS(§17.2 序列顺序即色序)。
*
* props 面封闭(G8):不接 className、不透传样式。空数据(合计为 0)不渲染空白
* 坐标系(§17.5):传 `empty` 槽位则渲染之,否则渲染 null。
*/
export interface DonutChartItem {
/** 唯一标识(同时作 recharts nameKey) */
key: string
/** 系列名(tooltip 与图例) */
label: ReactNode
/** 数值(正数;0 项不画扇区) */
value: number
}
/** 环径档:sm = size-28(卡内紧凑)/ md = size-40(默认) */
const SIZE_CLASS = { sm: "size-28", md: "size-40" } as const
/** 内建文案缺省(中文常量;调用方可经 otherLabel 覆写接入 i18n)。 */
const DONUT_DEFAULT_LABELS = { other: "其他" }
export function DonutChart({
items,
total,
totalLabel,
formatValue,
legend = true,
legendColumns = 2,
size = "md",
empty,
ariaLabel,
otherLabel = DONUT_DEFAULT_LABELS.other,
}: {
items: DonutChartItem[]
/** 中心主数值(已格式化节点;缺省 = 各项合计走 formatValue) */
total?: ReactNode
/** 中心标签(总计下方弱化行,如「合计」) */
totalLabel?: ReactNode
/** 数值格式化(图例与 tooltip 共用) */
formatValue?: (value: number) => string
/** 是否渲染图例网格(默认 true) */
legend?: boolean
/** 图例列数(默认 2) */
legendColumns?: 1 | 2 | 3
/** 环径档(默认 md) */
size?: "sm" | "md"
/** 合计为 0 时的空态槽位(调用方传本地化 EmptyState;缺省渲染 null) */
empty?: ReactNode
/** 图表结论(role=img 的 aria-label,宪法 §17.6) */
ariaLabel?: string
/** 超过 8 类时的聚合项名称(默认「其他」) */
otherLabel?: ReactNode
}) {
const F = useFormatters()
const M = useMessages()
const valueFormatter = formatValue ?? ((value: number) => F.number(value))
const sum = items.reduce((acc, item) => acc + item.value, 0)
// 审计 P2-24:缺省不再渲染空白,给出本地化空态;调用方仍可用 empty 覆写。
if (sum <= 0)
return (
<>
{empty ?? (
<p className="text-xs text-muted-foreground">{M.common.empty}</p>
)}
</>
)
// 超过 8 类时聚合为「其他」,禁止色序循环复用(审计 P1-11)。
const grouped =
items.length > 8
? [
...items.slice(0, 7),
{
key: "__other__",
label: otherLabel,
value: items.slice(7).reduce((acc, item) => acc + item.value, 0),
},
]
: items
const config: ChartConfig = Object.fromEntries(
grouped.map((item) => [item.key, { label: item.label }]),
)
const data = grouped.map((item, index) => ({
key: item.key,
value: item.value,
fill: seriesColor(index),
}))
const legendItems = grouped.map((item, index) => ({
key: item.key,
label: item.label,
color: seriesColor(index),
value: item.value > 0 ? valueFormatter(item.value) : undefined,
percentage: F.percent(item.value / sum, { maximumFractionDigits: 1 }),
}))
return (
<div data-slot="donut-chart" className="flex w-full items-center gap-4">
<div
className={cn("relative shrink-0", SIZE_CLASS[size])}
role={ariaLabel ? "img" : undefined}
aria-label={ariaLabel}
>
<ChartContainer config={config} className="h-full w-full">
<PieChart>
<ChartTooltip
content={
<ChartTooltipContent hideLabel formatter={(value) => valueFormatter(Number(value))} />
}
/>
<Pie
data={data}
dataKey="value"
nameKey="key"
innerRadius="72%"
outerRadius="98%"
paddingAngle={2}
cornerRadius={3}
strokeWidth={0}
startAngle={90}
endAngle={-270}
/>
</PieChart>
</ChartContainer>
<div
aria-hidden
className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center"
>
<span className="font-mono text-xl font-semibold tabular-nums leading-tight text-foreground">
{total ?? valueFormatter(sum)}
</span>
{totalLabel != null && (
<span className="text-xs text-muted-foreground">{totalLabel}</span>
)}
</div>
</div>
{legend && (
<div className="min-w-0 flex-1">
<ChartLegendGrid items={legendItems} columns={legendColumns} />
</div>
)}
</div>
)
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
环形图一体件:ChartContainer + recharts PieChart + 图例网格;数据与色彩经 props 注入,recharts 为 optional peer。