⚡

BaseUIReact开发技能 base-ui-react

Base UI React 是 MUI 提供的无样式、可访问 React 组件库，用于开发可访问的 Web 组件。它支持渲染属性模式，集成 Floating UI 进行精准定位，适用于需要高度自定义样式和可访问性的前端开发场景。关键词：base-ui, React, 无样式组件, 可访问性, Floating UI, Radix UI 迁移, 渲染属性, 前端开发

前端开发 0 次安装 0 次浏览 更新于 3/8/2026

名称: base-ui-react 描述: MUI Base UI 无样式 React 组件，集成 Floating UI。用于可访问组件、Radix UI 迁移、渲染属性 API，或遇到定位、弹窗、v1.0 beta 问题。 关键词: base-ui, @base-ui-components/react, mui base ui, 无样式组件, 可访问组件, 渲染属性, radix 替代, radix 迁移, floating-ui, 定位器模式, headless ui, 可访问对话框, 可访问选择, 可访问弹出框, 可访问工具提示, 可访问手风琴, 数字字段, cloudflare workers ui, beta 组件 许可证: MIT 元数据: 版本: “2.0.0” 最后验证: “2025-11-18” 生产测试: true 令牌节省: “~62%” 错误预防: 10 包含模板: 7 包含参考: 3

Base UI React

状态: Beta (v1.0.0-beta.4) ⚠️ | 最后验证: 2025-11-18

Base UI 是什么？

MUI 的无样式、可访问 React 组件库：

  • 27+ 可访问组件
  • 渲染属性模式
  • 完整样式控制
  • Floating UI 集成
  • Radix UI 的替代

Beta 状态: v1.0.0-beta.4 (稳定 v1.0 预计 2025 年第四季度)

快速开始

安装

bun add @base-ui-components/react

基本对话框

import * as Dialog from '@base-ui-components/react/dialog';

export function MyDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>打开</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Backdrop />
        <Dialog.Popup>
          <Dialog.Title>标题</Dialog.Title>
          <Dialog.Description>内容</Dialog.Description>
          <Dialog.Close>关闭</Dialog.Close>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

基本选择

import * as Select from '@base-ui-components/react/select';

<Select.Root>
  <Select.Trigger>
    <Select.Value placeholder="选择" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Option value="1">选项 1</Select.Option>
        <Select.Option value="2">选项 2</Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

加载 references/setup-guide.md 获取完整示例。

核心组件

可用 (27+):

  • 对话框
  • 选择
  • 弹出框
  • 工具提示
  • 手风琴
  • 数字字段
  • 复选框
  • 开关
  • 标签页
  • 滑块
  • 等等…

关键规则

总是做 ✅

  1. 使用 Portal 用于弹窗（对话框、选择、弹出框）
  2. 使用 Positioner 用于浮动元素
  3. 添加 Backdrop 用于模态对话框
  4. 使用 Tailwind 样式（或任何 CSS）
  5. 使用渲染属性（不像 Radix 的 asChild）
  6. 测试可访问性（ARIA 内置）
  7. 处理 Portal 边缘情况（SSR、水合）
  8. 检查 beta 文档 以了解破坏性更改
  9. 使用 TypeScript 以获得更好的开发体验
  10. 在目标浏览器上测试

永远不要做 ❌

  1. 永远不要使用 asChild（使用渲染函数代替）
  2. 永远不要跳过 Portal 用于弹窗（定位会破坏）
  3. 永远不要跳过 Positioner（Floating UI 不会工作）
  4. 永远不要假设 API 稳定性（beta 软件）
  5. 永远不要跳过可访问性测试
  6. 永远不要与 React <19 一起使用（需要 React 19+）
  7. 永远不要跳过 Backdrop 用于模态
  8. 永远不要硬编码 z-index（使用 Portal）
  9. 永远不要跳过 SSR 测试（水合问题）
  10. 永远不要假设 Radix 兼容性（不同的 API）

与 Tailwind 一起使用

<Dialog.Popup className="rounded-lg bg-white p-6 shadow-xl dark:bg-gray-800">
  <Dialog.Title className="text-xl font-bold text-gray-900 dark:text-white">
    对话框标题
  </Dialog.Title>
  <Dialog.Description className="mt-2 text-gray-600 dark:text-gray-300">
    对话框内容在这里
  </Dialog.Description>
  <Dialog.Close className="mt-4 rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-600">
    关闭
  </Dialog.Close>
</Dialog.Popup>

常见用例

用例 1: 模态对话框

<Dialog.Root>
  <Dialog.Trigger className="btn">打开模态</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop className="fixed inset-0 bg-black/50" />
    <Dialog.Popup className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6">
      <Dialog.Title>确认操作</Dialog.Title>
      <Dialog.Description>您确定吗？</Dialog.Description>
      <Dialog.Close>取消</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>

用例 2: 下拉选择

<Select.Root>
  <Select.Trigger className="flex items-center gap-2 rounded border px-4 py-2">
    <Select.Value placeholder="选择选项" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner className="z-50">
      <Select.Popup className="rounded border bg-white shadow-lg">
        <Select.Option value="1" className="px-4 py-2 hover:bg-gray-100">
          选项 1
        </Select.Option>
        <Select.Option value="2" className="px-4 py-2 hover:bg-gray-100">
          选项 2
        </Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

用例 3: 工具提示

import * as Tooltip from '@base-ui-components/react/tooltip';

<Tooltip.Root>
  <Tooltip.Trigger>悬停我</Tooltip.Trigger>
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup className="rounded bg-gray-900 px-2 py-1 text-sm text-white">
        工具提示文本
      </Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>

Beta 注意事项

生产稳定:

  • 对话框
  • 弹出框
  • 工具提示
  • 选择
  • 手风琴

谨慎使用:

  • 数字字段（API 可能更改）
  • 复杂表单组件

迁移路径:

  • v1.0 稳定预计 2025 年第四季度
  • 破坏性更改将被记录
  • 可能提供代码修改工具

与 Radix UI 对比

特性 Base UI Radix UI
模式 渲染属性 asChild
定位 内置 Floating UI 手动
Beta 是 稳定
Tree-shaking 更好 好
包大小 更小 更大

何时使用 Base UI:

  • 偏好渲染属性
  • 需要内置定位
  • 想要更小的包
  • 可以接受 beta

何时使用 Radix:

  • 需要稳定性
  • 偏好 asChild 模式
  • 成熟的生态系统

资源

参考 (references/):

  • example-reference.md - 详细组件示例和模式
  • migration-from-radix.md - 从 Radix UI 的完整迁移指南（包括渲染属性模式解释）
  • setup-guide.md - 安装和设置步骤

模板 (templates/):

  • Accordion.tsx - 手风琴组件与渲染属性
  • Dialog.tsx - 模态对话框示例
  • NumberField.tsx - 带验证的数字输入
  • Popover.tsx - 带定位的弹出框
  • Select.tsx - 选择下拉
  • Tooltip.tsx - 工具提示组件
  • migration-example.tsx - Radix 到 Base UI 迁移示例

官方文档

有问题？问题？

  1. 检查 references/setup-guide.md 以进行设置
  2. 查看 beta 状态警告
  3. 查看官方文档以获取最新更新
  4. 如果需要稳定性，考虑 Radix