Ordo UI
组件Navigation

Tabs

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

tabs@mox-hub/uiNavigationcanonicalsrc/components/tabs.tsx

变体轴

variant
defaultsegmentedline
orientation
horizontalverticalTabs 根组件的方向 prop
size
defaultsmTabsList 密度档;sm 为紧凑档(DF-07),372px 内可容纳 6 个 line Tab
变体演示tabs
账号设置内容。
372px 右栏的紧凑档:6 个 Tab 不溢出。

Props API

Prop类型默认值说明
className*string | ((state: TabsRootState) => string)——
orientation*Orientation"horizontal"—

源码

packages/ui/src/components/tabs.tsx
import { Tabs as TabsPrimitive } from "@base-ui/react/tabs"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "../lib/utils"

function Tabs({
  className,
  orientation = "horizontal",
  ...props
}: TabsPrimitive.Root.Props) {
  return (
    // base-ui 输出的是 data-orientation="horizontal|vertical"(无布尔 data-horizontal),
    // 方向选择器必须写 data-[orientation=…] 完整形态,裸写恒不匹配(左右布局事故根因)。
    // 默认(水平页签)上下堆叠:滑轨在内容块上方,w-fit 靠左上角对齐。
    <TabsPrimitive.Root
      data-slot="tabs"
      data-orientation={orientation}
      className={cn(
        "group/tabs flex flex-col gap-2 data-[orientation=vertical]:flex-row",
        className
      )}
      {...props}
    />
  )
}

const tabsListVariants = cva(
  "group/tabs-list inline-flex w-fit items-center justify-center rounded-lg p-1 text-muted-foreground group-data-[orientation=horizontal]/tabs:h-control-md group-data-[orientation=vertical]/tabs:h-fit group-data-[orientation=vertical]/tabs:flex-col data-[variant=line]:rounded-none",
  {
    variants: {
      variant: {
        default: "bg-muted/70 backdrop-blur-xs border border-border/50",
        // 项目扩展变体:胶囊滑块页签——轨道/滑块严格对齐 ui/segmented-control 规范
        // (border-border 实线、bg-background 实底无阴影、滑块 bg-muted/50、内容定宽不随容器拉伸)
        segmented:
          "relative gap-0 overflow-hidden rounded-full border border-border bg-background p-0.5 group-data-[orientation=horizontal]/tabs:h-control-sm",
        // line:详情页 body 内的次级切换——下划线贴边六件套内聚为默认(F 类 J7/F5.1),
        // 消费面无需再手写 w-full/justify-start/border-b/p-0/h-auto
        line: "w-full justify-start gap-1 border-b bg-transparent p-0 group-data-[orientation=horizontal]/tabs:h-auto",
      },
    },
    defaultVariants: {
      variant: "default",
    },
  }
)

function TabsList({
  className,
  variant = "default",
  size = "default",
  ...props
}: TabsPrimitive.List.Props &
  VariantProps<typeof tabsListVariants> & {
    /**
     * 密度档(DF-07):
     * - default:常规档,触发器 px-2/py-1/text-sm
     * - sm:紧凑档,触发器 px-1.5/py-0.5/text-xs,line 变体在 372px 内可放 6 个 Tab
     */
    size?: "default" | "sm"
  }) {
  return (
    <TabsPrimitive.List
      data-slot="tabs-list"
      data-variant={variant}
      data-size={size}
      className={cn(
        tabsListVariants({ variant }),
        // 紧凑档:列表内距/间距收紧;line 保持贴边下划线(h-auto + p-0)。
        // 用 cn 合并同组类,避免与上面 variant 的 gap/p 由 CSS 顺序决出胜者。
        size === "sm" && [
          "gap-0.5",
          variant === "default" && "p-0.5",
          variant !== "line" &&
            "group-data-[orientation=horizontal]/tabs:h-control-sm!",
        ],
        className
      )}
      {...props}
    >
      {variant === "segmented" && (
        <TabsPrimitive.Indicator
          data-slot="tabs-indicator"
          // 滑块不带 z-index(对齐 segmented-control:靠 DOM 序垫在触发器之下),bg-muted/50 + shadow-xs 为规范档
          className="pointer-events-none absolute rounded-full bg-muted/50 shadow-xs transition-[left,top,width,height] duration-slow ease-out left-[var(--active-tab-left)] top-[var(--active-tab-top)] w-[var(--active-tab-width)] h-[var(--active-tab-height)]"
        />
      )}
      {props.children}
    </TabsPrimitive.List>
  )
}

function TabsTrigger({ className, ...props }: TabsPrimitive.Tab.Props) {
  return (
    <TabsPrimitive.Tab
      data-slot="tabs-trigger"
      className={cn(
        "relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap text-foreground/60 transition-[color,background-color,border-color,box-shadow] duration-fast group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start hover:text-foreground focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:outline-1 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 has-data-[icon=inline-end]:pe-1.5 has-data-[icon=inline-start]:ps-1.5 aria-disabled:pointer-events-none aria-disabled:opacity-50 dark:text-muted-foreground dark:hover:text-foreground group-data-[variant=default]/tabs-list:data-active:shadow-xs group-data-[variant=line]/tabs-list:data-active:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent dark:group-data-[variant=line]/tabs-list:data-active:bg-transparent dark:group-data-[variant=line]/tabs-list:data-active:border-transparent dark:group-data-[variant=line]/tabs-list:data-active:bg-transparent",
        // segmented:内容定宽(不吃 flex-1 拉伸)+ 规范内边距;激活底色交由滑块承担,触发器保持透明
        "group-data-[variant=segmented]/tabs-list:px-3 group-data-[variant=segmented]/tabs-list:flex-none group-data-[variant=segmented]/tabs-list:data-active:bg-transparent dark:group-data-[variant=segmented]/tabs-list:data-active:bg-transparent",
        "data-active:bg-background data-active:text-foreground dark:data-active:border-input dark:data-active:bg-input/30 dark:data-active:text-foreground",
        // 紧凑档(DF-07):text-xs + 更窄内距;! 保证压过 variant 的 px-3 / 基线 px-2。
        "group-data-[size=sm]/tabs-list:gap-1! group-data-[size=sm]/tabs-list:px-1.5! group-data-[size=sm]/tabs-list:py-0.5! group-data-[size=sm]/tabs-list:text-xs!",
        "after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-[orientation=horizontal]/tabs:after:inset-x-0 group-data-[orientation=horizontal]/tabs:after:bottom-[-5px] group-data-[orientation=horizontal]/tabs:after:h-0.5 group-data-[orientation=vertical]/tabs:after:inset-y-0 group-data-[orientation=vertical]/tabs:after:-end-1 group-data-[orientation=vertical]/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",
        className
      )}
      {...props}
    />
  )
}

function TabsContent({ className, ...props }: TabsPrimitive.Panel.Props) {
  return (
    <TabsPrimitive.Panel
      data-slot="tabs-content"
      className={cn("flex-1 text-sm outline-none", className)}
      {...props}
    />
  )
}

export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants }

可访问性与 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、TabsList、TabsTrigger、TabsContent 组合;value 与 onValueChange 受控,内容区可按需懒加载。窄栏多页签给 TabsList 传 size="sm"(紧凑档),不要再手写 px-1/text-xs 覆盖。