base-ui

Base UI (React)

Base UI 提供无样式、可组合的 React 组件。本技能侧重于组装多部分组件、使用 render prop 进行组合，并在你自行提供样式的同时满足无障碍要求。

快速导航（参考）

工具

• references/csp-provider.md
• references/direction-provider.md
• references/merge-props.md
• references/use-render.md

表单与输入

• references/form.md
• references/fieldset.md
• references/input.md
• references/number-field.md
• references/otp-field.md
• references/radio.md
• references/select.md
• references/slider.md
• references/switch.md

反馈与状态

• references/meter.md
• references/progress.md
• references/toast.md

菜单、导航、浮层

• references/drawer.md
• references/menu.md
• references/menubar.md
• references/navigation-menu.md
• references/popover.md
• references/preview-card.md
• references/tooltip.md

开关与控件

• references/toggle.md
• references/toggle-group.md
• references/toolbar.md

布局与分隔符

• references/scroll-area.md
• references/separator.md

v1.7.0 - v1.8.0 亮点

• Combobox 新增 createItems 集合 API，用于以编程方式构建选项集合。
• Avatar.Image 新增 keepMounted prop，使图像子树保持挂载（有助于避免重新挂载时的闪烁）。
• Toast 接受基于当前 toast 派生的函数式更新，并且 Toast.Title、Toast.Description 和 Toast.Action 均支持 render prop。
• Autocomplete 和 Combobox 会发出 input-press 和 cancel-open 变更事件详情；内联 Combobox 暴露 expanded 状态。
• Combobox.Item 和 Select.Item 会从各自的根组件继承禁用状态。
• Form 会按文档顺序聚焦第一个无效字段；在异步验证进行期间，Field 会发布中性有效性状态。
• 主要是无障碍修复、弹窗/浮层行为修复，以及抽屉、菜单、工具提示和滚动区域的包体积缩减。

v1.4.1 亮点

• mergeProps 现在能正确转发多参数事件处理函数，这对除事件外还接收额外详情/状态的包装回调很重要。
• 修复了 display: contents 下的可 Tab 聚焦性；请重新测试会扁平化 DOM 结构的自定义包装器和 render-prop 组合。
• 修复了快速悬停触发器时的弹窗尺寸问题，滚动容器内被裁剪项的高亮清除也更可靠。

v1.6.0 亮点

• OTPFieldPreview 命名空间重命名为 OTPField；请更新引用了该预览命名空间的导入。
• 对 Accordion、Alert Dialog、Autocomplete、Avatar、Checkbox、Dialog、Drawer、Field、Menu、Number Field、OTP Field 及其他组件进行了大量行为缺陷修复。

v1.5.0 亮点

• OTPField 用 normalizeValue() 取代了 sanitizeValue()，并改进了键盘快捷键以及验证组合行为。
• 基于弹窗的组件现在更一致地遵循受控 open 状态，这会影响 Popover、Menu、PreviewCard 及相关浮层。
• Form、Field 和 OTPField 不再使用旧的 flushSync 式验证时序模式；在保留任何本地验证调度变通方案之前，请重新测试。
• 修正了 NavigationMenu、Popover 和 ScrollArea 的 RTL 行为。
• Drawer.Viewport 现在会转发 style，这对自定义视口尺寸和动画布局约束很有用。

v1.4.0 亮点

• OTPField 作为预览原语推出，用于一次性密码和验证码输入。
• 隐藏输入暴露 form 和 suppressHydrationWarning，这在控件提交到外部表单或跨 SSR 边界水合时很重要。
• 在组合组件中，render 警告和 preventBaseUIHandler() 的运行时行为更加可靠。
• Drawer、NavigationMenu、Select、Slider、Toast 和 Switch 中的浮层/输入原语获得了重要的行为修复。

v1.3.0 亮点

• Drawer 现已稳定（不再是预览版），应将其视为一等公民的浮层基础组件。
• Autocomplete 和 Combobox 新增 InputGroup；Combobox、Select 和 Slider 新增 Label 部分。
• Drawer 新增 SwipeArea，用于明确的手势滑动交互区域。
• Tooltip 新增 closeOnClick；Toast 可关闭所有 toast。
• Checkbox、Radio Group 和 Switch 改进了对 aria-labelledby 的自动支持。
• v1.2.0 引入的 render prop 支持依然适用，包括惰性元素。

需要掌握的核心概念

• 无样式基础组件：所有视觉效果均来自你的 CSS/Tailwind/CSS Modules。Base UI 负责行为与无障碍。
• 多部分结构：大多数组件遵循 Root + 子部分（Trigger、Popup、Item 等）的模式。需显式地将它们组装起来。
• render prop：替换默认元素，或用自己的组件进行包裹；使用函数形式时，需通过 mergeProps 手动合并 props。
• 状态驱动样式：许多部分会暴露数据属性，例如 data-[popup-open]、data-[highlighted]、data-[pressed]、data-[checked]、data-[invalid] 等。
• 浮层使用 Portal：对于弹出框、菜单、工具提示、select、导航菜单内容和预览卡片，请使用 Portal + Positioner + Popup。

实践方案

1) 快速构建无障碍表单

• 用 Form 包裹输入项，以处理提交和错误汇总。
• 使用带 name 的 Field.Root，再用 Field.Label、Field.Control 和 Field.Error 处理标签和错误。
• 用 Fieldset.Root + Fieldset.Legend 对相关字段进行分组。
• 对于 Radio 组，可使用带 aria-labelledby 的 RadioGroup，或通过 Fieldset.Root 渲染 RadioGroup，并为每个选项使用 Field.Label。
• 确保每个表单控件都有可访问名称（标签或 Field/Fieldset 标注模式）。

2) 使用 render + mergeProps 进行组合

• 将 React 元素传给 render 时，Base UI 会自动合并 props。
• 将函数传给 render 时，需用 mergeProps 合并 Base UI 的 props 和你自己的 props。
• 在合并后的事件处理函数内，可使用 event.preventBaseUIHandler() 在需要时阻止 Base UI 的内部行为（仅限合成事件）。

3) 浮层与菜单（通过 Portal 渲染的 UI）

• 使用 Root + Trigger + Portal + Positioner + Popup 构建弹出层。
• 对于菜单和导航，按需添加 Item、Separator、Arrow 以及列表/视口部分。
• NavigationMenu.Link 支持 render，可用于框架路由链接。

4) Toast

• 用 Toast.Provider 包裹应用（或子树）。
• 使用 Toast.useToastManager() 创建 toast。
• 在 Toast.Portal 内渲染 Toast.Viewport，然后将 toasts 映射为 Toast.Root 条目，并搭配 Toast.Content、Toast.Title、Toast.Description 和 Toast.Close。

5) RTL 与 CSP 约束

• 对于 RTL 行为，请用 DirectionProvider 包裹，同时设置 dir="rtl"（provider 不会设置 DOM 方向）。
• 对于严格 CSP，请用 CSPProvider 包裹并传入 nonce，或者如果你的应用提供外部样式，则禁用内联样式元素。注意内联样式属性不受 CSPProvider 控制。

6) Slider 与范围

• 单值滑块：一个 Slider.Thumb。
• 范围滑块：传入数组，并为每个值渲染一个 Slider.Thumb；添加 index 以对齐 SSR。
• 在需要边缘对齐时，使用 thumbAlignment 调整滑块手柄对齐方式。

关键禁止事项

• 不要遗漏输入框、滑块、开关或单选组的无障碍标签。
• 不要期望 Base UI 提供默认样式；请自行应用样式。
• 对于需要脱离层叠/溢出上下文的浮层，不要忘记使用 Portal。
• 使用 render 的函数形式时，不要跳过 mergeProps。

输出预期

回复用户时，请提供：

• 应使用的具体 Base UI 组件（及其关键部分）。
• 简要的组装方案（Root + 各部分 + 相关时的 portal/positioner）。
• 一份关于无障碍和状态驱动样式的简短检查清单。

Links

• Documentation
• Releases
• GitHub
• npm