项目概述

Radix UI Primitives 是 React 生态中最具权威的无头（Headless）、无样式底层组件基建库。由 WorkOS 团队打造，它专门解决复杂交互组件中最棘手的问题：无障碍访问（WAI-ARIA）、键盘快捷焦点管理、层叠模态框、碰撞检测定位与屏幕阅读器兼容。

它不包含任何内置样式，作为坚固可靠的底层基石，支撑着包括 shadcn/ui 在内的全球无数高品质自研设计系统。

核心特性

🧱 纯粹无头（Headless Zero CSS）：零内置样式绑定，零 CSS 运行时开销，可自由结合 Tailwind CSS、CSS Modules 或任何样式方案。
♿️ 完美的 WAI-ARIA 无障碍：内建键盘导航规范、Roving Tabindex 焦点移动机制与语义属性管理。
🛡️ 复杂交互底层完备：模态框嵌套、Portal 传送门、浮层视口防溢出智能定位及背景滚动锁定一应俱全。
🧩 高组合性与 `asChild` 模式：通过多态 asChild 属性无缝代理子节点，避免多余的 DOM 嵌套。

快速上手与示例代码

npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu

无障碍弹窗调用示例

import React from "react";
import * as Dialog from "@radix-ui/react-dialog";

export default function DialogDemo() {
  return (
    <Dialog.Root>
      <Dialog.Trigger className="px-4 py-2 bg-foreground text-background rounded-lg font-medium">
        打开对话框
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50 backdrop-blur-xs" />
        <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-card p-6 rounded-2xl shadow-2xl border w-full max-w-md">
          <Dialog.Title className="font-bold text-lg">个人资料编辑</Dialog.Title>
          <Dialog.Description className="text-sm text-muted-foreground mt-1">
            严格遵循焦点锁定与 ESC 快捷关闭规范。
          </Dialog.Description>
          <Dialog.Close className="mt-4 px-3 py-1.5 bg-muted rounded-lg text-sm">完成并关闭</Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

技术选型建议与适用场景

非常适合：企业自研专属设计系统、组件库基础架构师、对无障碍合规性（A11y）有严苛要求的高标准产品。
不适用场景：希望 5 分钟内快速拖拽现成样式、不想自己编写 Tailwind/CSS 类名的小型外包快闪项目。

Radix UI Primitives

项目概述

核心特性

快速上手与示例代码

无障碍弹窗调用示例

技术选型建议与适用场景

讨论与评价

相关组件推荐

Kinetics (Colorion)

Ambient CSS

8bitcn/ui