radix-primitives

Radix Primitives

用于构建高品质设计系统的无样式、无障碍 React 组件。

概述

• 构建具有完整无障碍支持的自定义样式组件
• 了解 shadcn/ui 的底层工作原理
• 需要无需包装 div 的多态组合
• 实现复杂的 UI 模式（模态框、菜单、工具提示）

基础组件目录

覆盖层组件

基础组件	用例
Dialog	模态对话框、表单、确认操作
AlertDialog	危险操作确认
Sheet	侧边面板、移动端抽屉

弹出层组件

基础组件	用例
Popover	在触发器上显示丰富内容
Tooltip	简短的文本提示
HoverCard	悬停时显示预览卡片
ContextMenu	右键菜单

菜单组件

基础组件	用例
DropdownMenu	操作菜单
Menubar	应用菜单栏
NavigationMenu	网站导航

表单组件

基础组件	用例
Select	自定义下拉选择框
RadioGroup	单选组
Checkbox	布尔值切换
Switch	开／关切换
Slider	范围选择

折叠组件

基础组件	用例
Accordion	可展开的区块
Collapsible	单个切换内容
Tabs	选项卡界面

核心模式：asChild

asChild 属性支持多态渲染，无需包装 div：

// Without asChild - creates nested elements
<Button>
  <Link href="/about">About</Link>
</Button>

// With asChild - merges into single element
<Button asChild>
  <Link href="/about">About</Link>
</Button>

工作原理：

• 使用 Radix 内部的 Slot 组件
• 将父组件的属性合并到子组件
• 正确转发 refs
• 合并事件处理器（两者都会触发）
• 合并 classNames

内置无障碍支持

每个基础组件都包含：

• 键盘导航：方向键、Escape、Enter、Tab
• 焦点管理：焦点陷阱、焦点返回、可见的焦点环
• ARIA 属性：角色、状态、属性
• 屏幕阅读器：恰当的播报

使用数据属性设置样式

Radix 通过数据属性公开状态：

/* Style based on state */
[data-state="open"] { /* open styles */ }
[data-state="closed"] { /* closed styles */ }
[data-disabled] { /* disabled styles */ }
[data-highlighted] { /* keyboard focus */ }

// Tailwind arbitrary variants
<Dialog.Content className="data-[state=open]:animate-in data-[state=closed]:animate-out">

快速参考

import { Dialog, DropdownMenu, Tooltip } from 'radix-ui'

// Basic Dialog
<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Title>Title</Dialog.Title>
      <Dialog.Description>Description</Dialog.Description>
      <Dialog.Close>Close</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

关键决策

决策	建议
样式方案	数据属性 + Tailwind 任意变体
组合方式	使用 asChild 避免包装 div
动画	仅使用 CSS，并通过 data-state 选择器控制
表单组件	与 react-hook-form 结合使用

相关技能

• shadcn-patterns - 带预设样式的 Radix 组件
• focus-management - 无障碍模式
• design-system-starter - 设计系统基础

参考

• asChild 组合 - 多态渲染
• Dialog 模式 - Dialog 和 AlertDialog
• Dropdown 模式 - 菜单和 Select
• Popover 模式 - Popover 和 Tooltip
• 焦点管理 - 键盘与焦点