Ordo UI
PatternsData Display

ProportionBar

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

proportion-bar@mox-hub/patternsData Displaycanonicalsrc/components/proportion-bar.tsx
变体演示proportion-bar

Props API

Prop类型默认值说明
segments*ProportionBarSegment[]——
total*number——
formatValue*(value: number) => string——
legend*booleantrue—
legendColumns*1 | 2 | 32—
empty*ReactNode——
ariaLabel*string——
otherLabel*ReactNodePROPORTION_BAR_DEFAULT_LABELS.other—

源码

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

用法说明

分段比例条:各段按占比横向拼接,余量斜纹呈现;图例与百分比走 ChartLegendGrid/format,数据经 props 注入。