radix-primitives

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Radix Primitives

Unstyled, accessible React components for building high-quality design systems.

用于构建高质量设计系统的无样式、可访问的React组件。

Overview

概述

Building custom styled components with full accessibility
Understanding how shadcn/ui works under the hood
Need polymorphic composition without wrapper divs
Implementing complex UI patterns (modals, menus, tooltips)

构建具备完整可访问性的自定义样式组件
理解shadcn/ui的底层工作机制
需要无外层div的多态组合
实现复杂UI模式（模态框、菜单、提示框）

Primitives Catalog

原语目录

Overlay Components

浮层组件

Primitive	Use Case
Dialog	Modal dialogs, forms, confirmations
AlertDialog	Destructive action confirmations
Sheet	Side panels, mobile drawers

原语	使用场景
Dialog	模态对话框、表单、确认弹窗
AlertDialog	危险操作确认弹窗
Sheet	侧边面板、移动端抽屉

Popover Components

弹出组件

Primitive	Use Case
Popover	Rich content on trigger
Tooltip	Simple text hints
HoverCard	Preview cards on hover
ContextMenu	Right-click menus

原语	使用场景
Popover	触发后显示富内容弹窗
Tooltip	简单文本提示框
HoverCard	悬停预览卡片
ContextMenu	右键菜单

Menu Components

菜单组件

Primitive	Use Case
DropdownMenu	Action menus
Menubar	Application menubars
NavigationMenu	Site navigation

原语	使用场景
DropdownMenu	操作菜单
Menubar	应用程序菜单栏
NavigationMenu	网站导航菜单

Form Components

表单组件

Primitive	Use Case
Select	Custom select dropdowns
RadioGroup	Single selection groups
Checkbox	Boolean toggles
Switch	On/off toggles
Slider	Range selection

原语	使用场景
Select	自定义选择下拉框
RadioGroup	单选组
Checkbox	布尔值切换按钮
Switch	开关切换按钮
Slider	范围选择滑块

Disclosure Components

展开/折叠组件

Primitive	Use Case
Accordion	Expandable sections
Collapsible	Single toggle content
Tabs	Tabbed interfaces

原语	使用场景
Accordion	可展开/折叠的内容区块
Collapsible	单开关控制的内容区块
Tabs	标签页界面

Core Pattern: asChild

核心模式：asChild

The

asChild

prop enables polymorphic rendering without wrapper divs:

tsx

// 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>

How it works:

Uses Radix's internal
```
Slot
```
component
Merges props from parent to child
Forwards refs correctly
Combines event handlers (both fire)
Merges classNames

asChild

属性支持无需外层div的多态渲染：

tsx

// 不使用asChild - 会创建嵌套元素
<Button>
  <Link href="/about">About</Link>
</Button>

// 使用asChild - 合并为单个元素
<Button asChild>
  <Link href="/about">About</Link>
</Button>

工作原理：

基于Radix内部的
```
Slot
```
组件实现
将父组件的属性合并到子组件
正确转发ref
合并事件处理器（两者都会触发）
合并类名

Built-in Accessibility

内置可访问性

Every primitive includes:

Keyboard navigation: Arrow keys, Escape, Enter, Tab
Focus management: Trap, return, visible focus rings
ARIA attributes: Roles, states, properties
Screen reader: Proper announcements

每个原语都包含：

键盘导航：方向键、Esc、Enter、Tab键
焦点管理：焦点陷阱、返回原焦点、可见焦点环
ARIA属性：角色、状态、属性
屏幕阅读器：正确的语音播报

Styling with Data Attributes

使用数据属性进行样式定制

Radix exposes state via data attributes:

css

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

tsx

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

Radix通过数据属性暴露组件状态：

css

/* 根据状态设置样式 */
[data-state="open"] { /* 展开状态样式 */ }
[data-state="closed"] { /* 收起状态样式 */ }
[data-disabled] { /* 禁用状态样式 */ }
[data-highlighted] { /* 键盘聚焦样式 */ }

tsx

// Tailwind 任意变体
<Dialog.Content className="data-[state=open]:animate-in data-[state=closed]:animate-out">

Quick Reference

快速参考

tsx

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>

tsx

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

// 基础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>

Key Decisions

关键决策建议

Decision	Recommendation
Styling approach	Data attributes + Tailwind arbitrary variants
Composition	Use `asChild` to avoid wrapper divs
Animation	CSS-only with data-state selectors
Form components	Combine with react-hook-form

决策项	建议方案
样式方案	数据属性 + Tailwind 任意变体
组合方式	使用 `asChild` 避免外层div
动画实现	结合data-state选择器的纯CSS动画
表单组件	与react-hook-form配合使用

Related Skills

References

参考资料

asChild Composition - Polymorphic rendering
Dialog Patterns - Dialog and AlertDialog
Dropdown Patterns - Menus and Select
Popover Patterns - Popover and Tooltip
Focus Management - Keyboard and focus

asChild 组合方式 - 多态渲染
对话框模式 - Dialog和AlertDialog
下拉菜单模式 - 菜单和选择器
弹出框模式 - 弹出框和提示框
焦点管理 - 键盘与焦点控制

radix-primitives

Original

Translation

Radix Primitives

Radix Primitives

Overview

概述

Primitives Catalog

原语目录

Overlay Components

浮层组件

Popover Components

弹出组件

Menu Components

菜单组件

Form Components

表单组件

Disclosure Components

展开/折叠组件

Core Pattern: asChild

核心模式：asChild

Built-in Accessibility

内置可访问性

Styling with Data Attributes

使用数据属性进行样式定制

Quick Reference

快速参考

Key Decisions

关键决策建议

Related Skills

相关技能

References

参考资料