# 基础 UI React **状态**：Beta (v1.0.0-beta.4) - 稳定版 v1.0 预计将于 2025 年第 4 季度发布 **最后更新**：2025-11-07 **依赖项**：React 19+、Vite（推荐）、Tailwind v4（推荐） **最新版本**：@base-ui-components/react@1.0.0-beta.4 ** ** ## ⚠️ 重要测试状态通知基本 UI 目前处于**测试版**。在生产中使用之前： * ✅ **稳定**：核心组件（对话框、弹出框、工具提示、选择、手风琴）已可投入生产 * ⚠️ **API 可能会更改**：v1.0（2025 年第 4 季度）之前可能会发生细微的重大更改 * ✅ **经过生产测试**：在实际项目中使用并记录了解决方法 * ⚠️ **已知问题**：此技能中包含 10 多个已记录的问题及其解决方案 * ✅ **迁移路径**：包含 Radix UI 的清晰迁移指南 **建议**：用于适合测试版软件的新项目。等待关键生产应用程序的 v1.0。 ** ** ## 快速入门（5 分钟） ### 1\.安装基本用户界面 pnpm 添加@base-ui-components/react **为什么这很重要：** * 单个包包含所有 27 个以上可访问的组件 * 除了 React 之外没有对等依赖 * Tree-shakeable - 只导入你需要的东西 * 适用于任何样式解决方案（Tailwind、CSS 模块、Emotion 等） ### 2\.使用您的第一个组件 // src/App.tsx 从“@base-ui-components/react/dialog”导入{Dialog}；导出函数 App() { 返回（ <对话框.根> {/* 渲染道具模式 - 基本 UI 的关键功能 */} <对话框.触发器渲染={(道具)=>( } /> {/* Positioner 使用 Floating UI 进行智能定位 */} <弹出框.定位器 side="top" // 上、右、下、左 alignment="center" // 开始、居中、结束侧偏移={8} > <弹出框.Portal> (

内容

)} /> ** ** ## Render Prop 模式（对比 Radix 的 asChild） ### 为什么要渲染道具？基本 UI 使用 **render props** 而不是 Radix 的 **asChild** 模式。这提供了： ✅ **显式道具传播** \- 清除正在应用哪些道具 ✅ **更好的 TypeScript 支持** \- 道具的完整类型推断 ✅ **更轻松的调试** \- 在开发工具中检查道具 ✅ **组合灵活性** \- 组合多个渲染函数 ### 比较 **Radix UI（asChild）**：从“@radix-ui/react-dialog”导入*作为对话框； <按钮>打开 **基本 UI（渲染属性）**：从“@base-ui-components/react/dialog”导入{Dialog}； <对话框.触发器渲染={(道具)=>( )} /> **主要区别**：渲染道具使道具传播**显式**（`{...props}`），而asChild则**隐式**。 ** ** ## 定位器模式（浮动 UI 集成）浮动组件（Select、Popover、Tooltip）使用 **Positioner** 模式： ### 不带定位器（错误） // ❌ 这不会正确定位 <弹出框.根> {/* 缺少定位逻辑 */} ### 带定位器（正确） // ✅ Positioner 处理浮动 UI 定位 <弹出框.根> <弹出框.Portal> ### 定位选项 <定位器 side="顶部" // 顶部 |对|底部|左对齐=“中心”//开始|中心 |结束 sideOffset={8} // 触发器和弹出窗口之间的间隙 alignmentOffset={0} // 沿对齐轴移动 CollisionBoundary={null} // null = 视口或 HTMLElement CollisionPadding={8} // 从边界开始填充 /> ** ** ## 组件目录 ### 需要定位器的组件这些组件**必须**将`Popup`包装在`Positioner`中： * **选择** \- 自定义选择下拉菜单 * **Popover** \- 浮动内容容器 * **工具提示** \- 悬停/焦点工具提示 ### 不需要定位器的组件这些组件的定位是： * **对话框** \- 模式对话框 * **手风琴** \- 可折叠部分 * **NumberField** \- 带增量/减量的数字输入 * **复选框** 、 **单选** 、 **开关** 、 **滑块** \- 表单控件 ** ** ## 已知问题预防此技能可防止 **10+** 记录的问题： ### 问题#1：渲染道具不传播道具 **错误**：组件不响应触发器，没有辅助功能**来源**：（常见的初学者错误）**为什么会发生**：忘记在渲染函数中传播 `{...props}` **预防**： // ❌ 错误 - 未应用 props <触发渲染={() => <按钮>单击} /> // ✅ 正确 - 道具传播 } /> ### 问题#2：定位器包装缺失 **错误**：Popup 定位不正确，出现在错误的位置 **来源**： **为什么会发生**：直接使用 Popup 而不使用定位器来实现浮动组件 **预防**： // ❌ 错误——没有定位 <弹出框.根> // ✅ 正确 - 定位器处理定位 <弹出框.根> <弹出框.定位器> <弹出框.Portal> ### 问题#3：使用对齐而不是对齐 **错误**：TypeScript 错误“属性‘align’不存在” **来源**：Radix 迁移问题 **为什么会发生**：Radix 使用 `align`，Base UI 使用 `alignment` **预防**： // ❌ 错误 - Radix API <定位器align=“中心”/> // ✅ 正确 - 基本 UI API <定位器对齐=“中心”/> ### 问题#4：使用 asChild 模式 **错误**：“属性'asChild'不存在”**来源**：Radix迁移问题**为什么会发生**：尝试使用Radix的asChild模式**预防**： // ❌ 错误 - 基数模式 <作为子级触发> <按钮>点击 // ✅ 正确 - 基本 UI 模式 } /> ### 问题#5：期待自动门户 **错误**：弹出窗口在 DOM 中的错误位置呈现 **来源**： **为什么会发生**：门户必须在 Base UI 中明确（与 Radix 不同） **预防**： // ❌ 错误 - 没有 Portal <对话框.根> <对话框.触发器/> {/* 就地渲染 */} // ✅ 正确 - 显式 Portal <对话框.根> <对话框.触发器/> <对话.传送门> <对话框.弹出/> ### 问题 #6：箭头组件未设置样式 **错误**：箭头不可见 **来源**： **为什么会发生**：箭头需要显式样式（无默认值） **预防**： // ❌ 错误 - 看不见的箭头 <弹出框.箭头/> // ✅ 正确样式的箭头 <弹出框.箭头渲染={(道具)=>(

)} /> ### 问题 #7：内容与弹出窗口命名 **错误**：“对话框上不存在属性‘内容’” **来源**：Radix 迁移问题 **为什么会发生**：Radix 使用 `Content`，Base UI 使用 `Popup` **预防**： // ❌ 错误 - 基数命名 <对话框.内容>... // ✅ 正确 - 基本 UI 命名 ... ### 问题#8：叠加与背景命名 **错误**：“对话框上不存在属性‘Overlay’” **来源**：Radix 迁移问题 **为什么会发生**：Radix 使用 `Overlay`，Base UI 使用 `Backdrop` **预防**： // ❌ 错误 - 基数命名 <对话框.Overlay /> // ✅ 正确 - 基本 UI 命名 <对话框.背景/> ### 问题 #9：禁用按钮工具提示未显示 **错误**：工具提示未显示在禁用按钮上 **来源**： **为什么会发生**：禁用元素不会触发指针事件 **预防**： // ❌ 错误 - 工具提示不会显示 <工具提示.Root>

)} /> ）； } **何时使用**：模式中的表单、用户输入对话框 ### 模式 2：可搜索选择从“@base-ui-components/react/select”导入{选择}；从“反应”导入{useState}；常量选项 = [ { 值：“反应”，标签：“反应”}， { 值：“vue”，标签：“Vue”}， { 值：“角度”，标签：“角度”}， ]; 导出函数SearchableSelect() { const [值，setValue] = useState(""); const [搜索，setSearch] = useState(""); const 过滤 = options.filter((opt) => opt.label.toLowerCase().includes(search.toLowerCase()) ）；返回（ <选择.触发器渲染={(道具)=>( } /> ### 问题：弹出窗口出现在错误的位置 **解决方案**：包裹在定位器中： // ❌ 错误 // ✅ 正确 <弹出框.Portal> ### 问题：TypeScript 错误“属性‘align’不存在” **解决方案**：使用 `alignment` 而不是 `align`： // ❌ 错误（基数） <定位器align=“中心”/> // ✅ 正确（基本 UI） <定位器对齐=“中心”/> ### 问题：箭头不可见 **解决方案**：明确设置箭头样式： // ❌ 错误 <箭头/> // ✅ 正确 <箭头渲染={（道具）=>（

)} /> ### 问题：工具提示未显示在禁用按钮上 **解决方案**：将按钮包裹在跨度中： // ❌ 错误

对话框标题

输入您的名字

基本 Ui 反应

包含技能