SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场radix-ui

radix-ui

前端与建站

查看项目

更新于 10-15 11:11

技能介绍

用途

Radix UI 用于构建无障碍、可组合的 React 用户界面，覆盖从底层组件原语到预置样式设计系统的完整需求。官方文档地址为 https://www.radix-ui.com。

两个产品

产品 说明 安装 适用场景
Primitives 无样式、可访问的组件原语 npm i radix-ui 构建自定义设计系统，需要完全控制样式
Themes 基于 Primitives 的预置样式组件库 npm i @radix-ui/themes 需要开箱即用的生产级样式组件

资料说明：shadcn/ui 构建在 Radix Primitives 之上；若使用 shadcn，应改用 shadcn-ui 技能。

主要能力

Radix Primitives

核心原则：无样式（不附带 CSS，可用 Tailwind、CSS Modules、styled-components 等任意方式样式化）、可访问（遵循 WAI-ARIA 设计模式，完整键盘导航，经屏幕阅读器测试）、可组合（细粒度子组件、asChild 元素委托、受控/非受控模式）。

安装方式：

# 统一包（推荐，可 tree-shake）
npm install radix-ui

# 或单独安装
npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu

组件目录（Primitives）：

  • 覆盖层：Dialog、Alert Dialog、Popover、Hover Card、Tooltip
  • 菜单：Dropdown Menu、Context Menu、Menubar
  • 导航：Navigation Menu、Tabs
  • 表单：Checkbox、Radio Group、Select、Slider、Switch、Toggle、Toggle Group、Form
  • 展开收起：Accordion、Collapsible
  • 媒体：Avatar、Aspect Ratio、Progress
  • 布局：Scroll Area、Separator、Toolbar
  • 工具：Label、Portal、Slot、Visually Hidden、Direction Provider
  • 已弃用：Toast（建议改用 Sonner）

组合模型：每个组件拆分为具名部件进行组合，例如 Dialog.Root、Dialog.Trigger、Dialog.Portal、Dialog.Overlay、Dialog.Content、Dialog.Title、Dialog.Description、Dialog.Close。

asChild 属性：将渲染委托给子元素，把 Radix 行为合并到自定义组件上。自定义组件需满足：将所有 props 展开到 DOM 元素；使用 React.forwardRef 转发 ref（React 19 中可用 ref prop）。asChild 可嵌套以组合多个原语行为。

受控与非受控：所有有状态组件均支持两种模式，非受控为默认，受控时由开发者管理状态。

数据属性：Radix 通过 data-* 属性暴露状态供 CSS 样式化，包括 [data-state]（open/closed、checked/unchecked/indeterminate、active/inactive）、[data-disabled]、[data-orientation]、[data-highlighted]、[data-side]、[data-align]。

动画模式：推荐使用 CSS 动画，Radix 会在 CSS 动画期间暂停卸载以支持退出动画；Accordion 和 Collapsible 暴露尺寸变量（如 --radix-accordion-content-height）用于平滑高度动画；使用 JavaScript 动画库时可用 forceMount 阻止 Radix 卸载内容。

键盘导航：所有组件实现 WAI-ARIA 键盘模式，例如 Dialog 支持 Esc 关闭、Tab 焦点陷阱；Dropdown Menu 支持方向键导航、Enter/Space 选择、Esc 关闭；Accordion、Tabs、Select、Slider、Radio Group 均有对应键盘交互。

无障碍保证：Radix 自动处理 ARIA 属性、焦点管理、屏幕阅读器播报、键盘交互模式、通过 dir prop / DirectionProvider 支持 RTL。开发者需提供：对话框的 Title 和 Description（或使用 VisuallyHidden）、仅图标触发器的 aria-label、有意义的屏幕阅读器内容、合理的 Tab 顺序。

Radix Themes

预置样式组件库，内置主题系统，内部使用 Radix Primitives，附带样式、颜色系统和布局原语。

安装与初始化：

npm install @radix-ui/themes

// app/layout.tsx 或主入口
import "@radix-ui/themes/styles.css"
import { Theme } from "@radix-ui/themes"

export default function Layout({ children }) {
  return (
    <Theme accentColor="indigo" grayColor="slate" radius="medium" scaling="100%">
      {children}
    </Theme>
  )
}

主题配置项：accentColor（品牌色，24 种）、grayColor（中性色，6 种）、radius（none | small | medium | large | full）、scaling（全局尺寸缩放）、appearance（light | dark | inherit）、panelBackground（solid | translucent）。开发时可用 ThemePanel 交互式预览主题变化。

颜色系统：每种颜色有 12 级色阶，1-2 为背景，3-5 为交互状态，6-8 为边框，9-10 为实心填充，11-12 为文本。强调色共 24 种（Gray、Gold、Bronze、Brown、Yellow、Amber、Orange、Tomato、Red、Ruby、Crimson、Pink、Plum、Purple、Violet、Iris、Indigo、Blue、Cyan、Teal、Jade、Green、Grass、Lime、Mint、Sky），灰色 6 种（Gray、Mauve、Slate、Sage、Olive、Sand）。特殊令牌包括 --accent-surface、--accent-indicator、--accent-track、--accent-contrast、--color-background、--color-overlay。组件可单独覆盖颜色，如 <Button color="red">。

Themes 组件目录：布局（Box、Flex、Grid、Section、Container）、排版（Text、Heading、Code、Quote、Em、Strong、Kbd）、表单（Button、IconButton、TextField、TextArea、Select、Checkbox、Radio Group、Switch、Slider、SegmentedControl）、覆盖层（Dialog、Alert Dialog、Popover、Hover Card、Tooltip、Context Menu、Dropdown Menu）、数据展示（Table、Avatar、Badge、Callout、Card、Data List、Inset、Separator、Skeleton）、反馈（Progress、Spinner）、导航（Tabs、Tab Nav、Link）。多数组件共享 size、variant、color、highContrast、radius、loading、asChild 等属性。

使用方式

安装对应 npm 包后，按子组件结构组合使用；Primitives 需自行编写样式，Themes 引入 styles.css 并用 Theme 包裹应用。

适用场景

  • 构建自定义设计系统、需要完全样式控制时使用 Primitives
  • 需要开箱即用样式组件、快速原型时使用 Themes
  • 需要无障碍对话框、弹出层、下拉菜单、手风琴等组件时
  • 需要 asChild 组合、受控状态、data 属性样式化、进出场动画时

限制

资料未提供收费、价格、平台支持范围、性能数据或效果承诺等信息。Toast 组件已弃用，建议改用 Sonner。使用 asChild 的自定义组件必须正确转发 ref 并展开 props。对话框需自行提供 Title 和 Description。