PatternsData Display
ProportionBar
@mox-hub/patterns 模式 · Data Display · canonical
proportion-bar@mox-hub/patternsData Displaycanonicalsrc/components/proportion-bar.tsx变体演示proportion-bar
待办820%
进行中37.5%
已完成2152.5%
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| segments* | ProportionBarSegment[] | — | — |
| total* | number | — | — |
| formatValue* | (value: number) => string | — | — |
| legend* | boolean | true | — |
| legendColumns* | 1 | 2 | 3 | 2 | — |
| empty* | ReactNode | — | — |
| ariaLabel* | string | — | — |
| otherLabel* | ReactNode | PROPORTION_BAR_DEFAULT_LABELS.other | — |
源码
import type { ReactNode } from "react"
import { ChartLegendGrid, seriesColor } from "./chart-legend-grid"
import { useFormatters, useMessages } from "@mox-hub/ui/i18n"
/**
* ProportionBar —— 分段比例条(语义层,2026-10-11 图表重设计批)
*
* 「全宽分段条 + 斜纹余量 + 图例网格」一体件:各段按占比横向拼接,总量大于各段
* 合计时余量以斜纹(repeating-linear-gradient + border token,无字面色)呈现。
* 段色序走 SERIES_COLORS(§17.2 序列顺序即色序)。纯 div 实现,不进坐标系。
*
* props 面封闭(G8):不接 className、不透传样式。总量为 0(无数据)不渲染空条
* (§17.5 精神):传 `empty` 槽位则渲染之,否则渲染 null。
*/
/** 内建文案缺省(中文常量;调用方可经 otherLabel 覆写接入 i18n)。 */
const PROPORTION_BAR_DEFAULT_LABELS = { other: "其他" }
export interface ProportionBarSegment {
/** 唯一标识 */
key: string
/** 段名(图例) */
label: ReactNode
/** 数值(正数;0 段不画) */
value: number
}
export function ProportionBar({
segments,
total,
formatValue,
legend = true,
legendColumns = 2,
empty,
ariaLabel,
otherLabel = PROPORTION_BAR_DEFAULT_LABELS.other,
}: {
segments: ProportionBarSegment[]
/** 总量(分母;缺省 = 各段合计。大于合计时余量以斜纹呈现) */
total?: number
/** 数值格式化(图例用) */
formatValue?: (value: number) => string
/** 是否渲染图例网格(默认 true) */
legend?: boolean
/** 图例列数(默认 2) */
legendColumns?: 1 | 2 | 3
/** 总量为 0 时的空态槽位(调用方传本地化节点;缺省渲染 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 = segments.reduce((acc, segment) => acc + segment.value, 0)
const denom = total ?? sum
// 审计 P2-24:缺省不再渲染空白,给出本地化空态;调用方仍可用 empty 覆写。
if (denom <= 0)
return (
<>
{empty ?? (
<p className="text-xs text-muted-foreground">{M.common.empty}</p>
)}
</>
)
// 超过 8 类时聚合为「其他」,禁止色序循环复用(审计 P1-11)。
const grouped =
segments.length > 8
? [
...segments.slice(0, 7),
{
key: "__other__",
label: otherLabel,
value: segments.slice(7).reduce((acc, segment) => acc + segment.value, 0),
},
]
: segments
const filled = grouped.map((segment, index) => ({
...segment,
color: seriesColor(index),
pct: Math.max(segment.value / denom, 0),
}))
const remainderPct = Math.min(Math.max(1 - filled.reduce((acc, s) => acc + s.pct, 0), 0), 1)
return (
<div
data-slot="proportion-bar"
className="w-full space-y-2.5"
role={ariaLabel ? "img" : undefined}
aria-label={ariaLabel}
>
<div aria-hidden className="flex h-2.5 w-full overflow-hidden rounded-full bg-muted/60">
{filled.map((segment) =>
segment.pct > 0 ? (
<div
key={segment.key}
className="h-full"
style={{ width: `${segment.pct * 100}%`, backgroundColor: segment.color }}
/>
) : null,
)}
{remainderPct > 0 && (
<div
className="h-full flex-1"
style={{
backgroundImage:
"repeating-linear-gradient(45deg, hsl(var(--border)) 0 1px, transparent 1px 4px)",
}}
/>
)}
</div>
{legend && (
<ChartLegendGrid
items={filled.map((segment) => ({
key: segment.key,
label: segment.label,
color: segment.color,
value: segment.value > 0 ? valueFormatter(segment.value) : undefined,
percentage: F.percent(segment.pct, { maximumFractionDigits: 1 }),
}))}
columns={legendColumns}
/>
)}
</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。
用法说明
分段比例条:各段按占比横向拼接,余量斜纹呈现;图例与百分比走 ChartLegendGrid/format,数据经 props 注入。