Ordo UI
组件Controls

SegmentedControl

@mox-hub/ui 组件 · Controls · canonical

segmented-control@mox-hub/uiControlscanonicalsrc/components/segmented-control.tsx
变体演示segmented-control

Props API

Prop类型默认值说明
value*T——
options*SegmentedOption<T>[]——
onChange*(value: T) => void——
className*string——
ariaLabel*string——
variant*"rect" | "pill""pill"—

源码

packages/ui/src/components/segmented-control.tsx
import type { ReactNode } from "react";
import { useDirection } from "@base-ui/react/direction-provider";
import { cn } from "../lib/utils";

/** 选项高亮色调:激活滑块与文字按语义色着色(页面按需传入) */
export type SegmentedTone = "default" | "blue" | "green" | "yellow" | "red" | "purple";

export interface SegmentedOption<T extends string> {
  value: T;
  label: ReactNode;
  icon?: ReactNode;
  tone?: SegmentedTone;
}

interface SegmentedControlProps<T extends string> {
  value: T;
  options: SegmentedOption<T>[];
  onChange: (value: T) => void;
  className?: string;
  /** 组可访问名(#28);不传则保持无名称,由页面上下文补充 */
  ariaLabel?: string;
  /** pill:胶囊滑块(默认);rect:圆角矩形滑块(toolbar 居中切换用) */
  variant?: "pill" | "rect";
}

// A1 对比度:accent 文字在浅底/深底只有 3.11–4.42:1,统一用最深前景 token;
// tone 仍由 rect 滑块底色承载,颜色语义不丢失。
const TONE_CLASS: Record<SegmentedTone, { slider: string; label: string }> = {
  default: { slider: "border-border bg-background", label: "text-foreground" },
  blue: {
    slider: "border-accent-blue/40 bg-accent-blue-light",
    label: "text-foreground",
  },
  green: {
    slider: "border-accent-green/40 bg-accent-green-light",
    label: "text-foreground",
  },
  yellow: {
    slider: "border-accent-yellow/50 bg-accent-yellow-light",
    label: "text-foreground",
  },
  red: {
    slider: "border-accent-red/40 bg-accent-red-light",
    label: "text-foreground",
  },
  purple: {
    slider: "border-accent-purple/40 bg-accent-purple-light",
    label: "text-foreground",
  },
};

export function SegmentedControl<T extends string>({
  value,
  options,
  onChange,
  className,
  ariaLabel,
  variant = "pill",
}: SegmentedControlProps<T>) {
  const direction = useDirection();
  const activeIndex = options.findIndex((option) => option.value === value);
  const hasActive = activeIndex >= 0 && options.length > 0;

  const isRect = variant === "rect";
  const activeTone = TONE_CLASS[options[activeIndex]?.tone ?? "default"];
  // 滑块位移必须镜像:RTL 下网格从右往左排,正向 translateX 会把滑块推出容器。
  const slideOffset = direction === "rtl" ? -activeIndex : activeIndex;

  return (
    <div
      role="group"
      aria-label={ariaLabel}
      data-slot="segmented-control"
      className={cn(
        // 审计 P2-35:与 ui/tabs 的 segmented 档共用 32px 高度(h-control-sm),
        // 滑块/按钮不再靠 py 撑到 ~38px。
        "relative inline-grid h-control-sm overflow-hidden p-0.5",
        isRect
          ? "rounded-md border border-border bg-muted/50"
          : "rounded-full border border-border bg-background",
        className,
      )}
      style={{ gridTemplateColumns: `repeat(${Math.max(options.length, 1)}, minmax(0, 1fr))` }}
    >
      {hasActive && (
        <span
          data-slot="segmented-control-slider"
          className={cn(
            "pointer-events-none absolute bg-muted/50 shadow-xs transition-transform duration-slow ease-out",
            isRect ? "inset-0.5 rounded-sm border" : "inset-y-0.5 rounded-full",
            isRect && activeTone.slider,
          )}
          style={{
            width: `calc((100% - 4px) / ${Math.max(options.length, 1)})`,
            transform: `translateX(calc(${slideOffset} * 100%))`,
          }}
          aria-hidden="true"
        />
      )}
      {options.map((option) => (
        <button
          key={option.value}
          type="button"
          aria-pressed={value === option.value}
          onClick={() => onChange(option.value)}
          className={cn(
            "relative z-sticky flex h-full items-center justify-center gap-1 rounded-full px-3 py-0 text-sm transition-colors duration-fast outline-none focus-visible:ring-2 focus-visible:ring-ring/50",
            isRect && "rounded-sm",
            value === option.value
              ? isRect
                ? activeTone.label
                : "text-foreground"
              : "text-muted-foreground hover:text-foreground",
          )}
        >
          {option.icon}
          {option.label}
        </button>
      ))}
    </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。

用法说明

分段选择器,少量互斥选项平铺;与 tabs 的区别是它不切换内容区。