组件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" | — |
源码
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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
分段选择器,少量互斥选项平铺;与 tabs 的区别是它不切换内容区。