Ordo UI
PatternsData Display

DonutChart

@mox-hub/patterns 模式 · Data Display · canonical

donut-chart@mox-hub/patternsData Displaycanonicalsrc/components/donut-chart.tsx

变体轴

size
smmd
变体演示donut-chart
待办825%
进行中39.4%
已完成2165.6%

Props API

Prop类型默认值说明
items*DonutChartItem[]——
total*ReactNode——
totalLabel*ReactNode——
formatValue*(value: number) => string——
legend*booleantrue—
legendColumns*1 | 2 | 32—
size*"sm" | "md""md"—
empty*ReactNode——
ariaLabel*string——
otherLabel*ReactNodeDONUT_DEFAULT_LABELS.other—

源码

packages/patterns/src/components/donut-chart.tsx
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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

环形图一体件:ChartContainer + recharts PieChart + 图例网格;数据与色彩经 props 注入,recharts 为 optional peer。