# 基本 UI 指南 Base UI (`@base-ui/react`) 是一个无样式的 React 组件库，用于构建可访问的用户界面。来自 Radix、Material UI 和 Floating UI 的创建者。组件是无头的、可组合的并且符合 WAI-ARIA 标准。支持 React 17+ 和所有现代浏览器（基线广泛可用）。 Tree-shakeable 单包。 **请勿将本指南用于 Radix UI (radix-ui)、Material UI (MUI @mui/material) 或 Shadcn/ui — 这些是具有不同 API 的独立库。 ## 快速入门 npm 我@base-ui/react ### 设置 1. **Portals** \- 添加堆叠上下文隔离以防止 z-index 冲突： .root { 隔离：隔离； }

{children}

2. **iOS 26+ Safari** \- 对于对话框背景：身体{位置：相对; } ## 导入模式所有组件都使用来自单个包的命名空间复合模式：从 '@base-ui/react/popover' 导入 { Popover }； <弹出框.根> 打开 <弹出框.Portal> <弹出窗口.弹出窗口> <弹出框.箭头/> 标题内容 ## 核心模式 ### 样式（组件完全没有样式） **CSS 类** \- 静态或状态相关： state.checked ? '选中' : '未选中'} /> **数据属性** \- 所有组件通过“data-*”属性公开状态： .SwitchThumb[数据检查] { 背景：蓝色； } .Popup[数据开始样式] { 不透明度: 0;变换：缩放（0.9）； } **CSS 自定义属性** \- 布局/动画的动态值： .Indicator { 宽度：var(--slider-indicator-width); } .Popup { 变换原点：var(--变换原点); } 适用于 Tailwind CSS、CSS 模块、CSS-in-JS 或纯 CSS。 ### 组合（渲染道具）用自定义组件或不同的 HTML 标签替换默认元素： // 自定义组件（必须转发 ref 和 spread 属性） } /> // 不同的 HTML 元素 }>配置文件 // 具有状态访问的渲染函数 ( {state.checked ? : } )} /> ### 服务器组件 (Next.js / RSC) 所有交互式基本 UI 组件都需要在 React 服务器组件环境中“使用客户端”。服务器组件中只能使用静态显示组件（Separator、没有交互的 Avatar）。 ### 组合框列表渲染模式组合框和自动完成在“List”上使用独特的渲染子模式 - 传递一个接收每个过滤项的函数： <组合框.列表> {（项目）=>（ {项目.标签} )} 这与 Select 不同，在 Select 中，您显式地对“Select.List”内的项目使用“.map()”。 ### 受控与不受控所有交互组件都支持两种模式： // 不受控制（内部状态） // 受控（外部状态） ### 活动定制更改处理程序接收 `(value, eventDetails)`： { if (details.reason === '转义键') { 详细信息.取消(); // 防止关闭 } }}> 关键的“eventDetails”方法：“cancel()”、“allowPropagation()”。访问“原因”以了解发生更改的原因。＃＃＃动画片 **CSS 转换**（推荐 - 可以中途取消）： .弹出窗口{ 过渡：变换150ms，不透明度150ms；变换原点：var(--变换原点); } .Popup[数据启动样式], .Popup[数据结束样式] { 不透明度：0；变换：缩放（0.9）； } **CSS 动画** ：将 `[data-open]` / `[data-close]` 与 `@keyframes` 一起使用。 **JavaScript（运动）** ：使用 `keepMounted` \+ `render` 属性 + ``。 ### 打字稿按命名空间组织的类型： Tooltip.Root.Props // 组件道具 Popover.Positioner.State // 内部状态类型 Combobox.Root.ChangeEventDetails // 事件详细信息类型 ## 组件目录 ### 叠加和导航组件|零件 |描述 ---|---|--- **对话框** |根、触发器、门户、背景、弹出窗口、标题、描述、关闭 |带有焦点陷阱的模态对话框 **警报对话框** |根、触发器、门户、背景、弹出窗口、标题、描述、关闭 |确认对话框（无指针关闭） **弹出窗口** |根、触发器、门户、定位器、弹出窗口、箭头、标题、描述 |非模态浮动内容 **工具提示** |提供程序、根、触发器、门户、定位器、弹出窗口、箭头 |悬停/焦点信息弹出窗口 **预览卡** |根、触发器、门户、定位器、弹出、箭头 |链接悬停预览 **吐司** |提供者、门户、视口、根、标题、描述、操作、关闭 |通知 toast（堆叠或锚定） **菜单** |根、触发器、门户、定位器、弹出窗口、箭头、项目、组、分隔符 + 单选/复选框项目 |带有子菜单的下拉菜单 **上下文菜单** |根菜单、触发器、门户、定位器、弹出菜单、项目、组 + 子菜单 |右键单击上下文菜单 **导航菜单** |根、列表、项目、触发器、内容、门户、定位器、弹出窗口、链接 |带面板的站点导航 **菜单栏** |包装器 + Menu.Root 实例 |水平应用程序菜单栏 ### 表单控件组件|零件 |描述 ---|---|--- **表格** |单包装|包含验证和提交的表单 **领域** |根、标签、控制、描述、错误、有效性 |带验证的字段包装器 **字段集** |根，传说|组相关字段 **输入** |单元素|具有状态数据属性的文本输入 **数字字段** |根、ScrubArea、组、减量、输入、增量|带步进器的数字输入 **复选框** |根，指标|具有不确定支持的复选框 **复选框组** |根|管理多个复选框状态 **广播** |根、指示符 + RadioGroup |单选按钮组 **选择** |根、触发器、值、门户、定位器、弹出窗口、列表、项目、项目指示器 |下拉选择 **组合框** |根、输入、触发器、门户、定位器、弹出窗口、列表、项目 + 芯片 |可搜索选择并进行过滤 **自动完成** |根、输入、触发器、门户、定位器、弹出窗口、列表、项目 |带有建议的文本输入 **开关** |根、拇指|拨动开关 **滑块** |根、值、控制、跟踪、指示器、拇指 |范围滑块（单拇指或多拇指） **切换** |单元素|可按下的切换按钮 **切换组** |包装+切换子项|独占或多选切换 **按钮** |单元素|无障碍按钮 ### 显示和布局组件|零件 |描述 ---|---|--- **手风琴** |根、项目、标题、触发器、面板|可扩展的内容部分 **可折叠** |根、触发器、面板|单展开/折叠 **标签** |根目录、列表、选项卡、指示器、面板 |选项卡式界面 **滚动区域** |根、视口、内容、滚动条、拇指、角|自定义滚动条 **工具栏** |根、按钮、链接、分隔符、组、输入 |操作工具栏 **分隔符** |单元素 |视觉分隔线 **进展** |根、轨道、指示符、值、标签|进度条 **仪表** |根、轨道、指示符、值、标签|仪表/仪表显示 **头像** |根、图像、后备|具有后备功能的个人资料图片 ### 实用程序实用程序 |目的 ---|--- **CSP 提供商** |将随机数应用于 CSP 的内联样式/脚本 **方向提供商** |启用组件的 RTL 行为 **mergeProps** |使用特殊处理程序/类/样式合并来合并 React props **使用渲染** |用于在自定义组件中启用渲染道具模式的钩子 ## 关键规则 1. **始终在应用程序根目录上使用`isolation:isolate`**以进行门户 z-index 堆叠 2. **组件无样式** \- 您必须提供所有 CSS 3. **`render`中的自定义组件必须转发 ref 和 spread props** 4. **使用数据属性进行基于状态的样式**，而不是类名切换 5. **CSS 过渡 > CSS 动画** 用于可中断的打开/关闭效果 6. **动画不透明度**（甚至 0.9999），以便 Base UI 在卸载之前检测动画完成情况 7. **表单字段需要Field.Root上的`name`属性**用于表单提交 8. **Field.Label 使用 `nativeLabel` 属性** \- 为基于按钮的控件（Select、Combobox）设置 `false` 9. **弹出组件**如下：根 > 触发器 > Portal > 定位器 > 弹出 > 箭头图案 10. **`preventBaseUIHandler()`** 在 React 事件上绕过 Base UI 的内部事件处理 ## 常见陷阱 * **门户 z-index 问题**：忘记应用程序根目录上的“隔离：隔离” - 弹出窗口出现在内容后面 * **动画未完成** ：不为 `opacity` 设置动画 \- 基础 UI 使用 `element.getAnimations()` 来检测完成；如果不需要的话，将不透明度动画设置为“0.9999” * **选择/组合框标签未关联** ：对于基于按钮的控件（选择、组合框），需要在“Field.Label”上使用“nativeLabel={false}” * **出现在内容后面的弹出窗口**：缺少“Portal”包装器或未设置堆叠上下文 * **提交时未收集表单值**：“Field.Root”上缺少“name”属性 * **嵌套弹出窗口全部在 Esc 上关闭** ：默认行为停止传播；如果您希望父弹出窗口也关闭，请使用“eventDetails.allowPropagation()” * **运动退出动画不播放** ：必须在 Portal 上使用 `keepMounted` + 受控的 `open` 状态 + 对于未安装的组件使用 `` ## 常见 CSS 变量弹出/浮动组件公开： * `--anchor-width`, `--anchor-height` \- 触发元素尺寸 * `--available-width`, `--available-height` \- 可用空间 * `--transform-origin` \- 动画原点调整组件大小暴露： * `--accordion-panel-height`, `--collapsible-panel-height` \- 面板尺寸 * `--slider-*`, `--scroll-area-*` \- 组件特定的大小调整 * `--active-tab-left`, `--active-tab-width` \- 选项卡指示器定位 ## 参考文件 * `references/components-dialogs.md` \- 对话框、AlertDialog、Popover、工具提示、PreviewCard * `references/components-menus.md` \- Toast、菜单、ContextMenu、NavigationMenu、Menubar、共享模式 * `references/components-form-fields.md` \- 表单、字段、字段集、输入、NumberField、复选框、CheckboxGroup、单选 * `references/components-form-controls.md` \- 选择、组合框、自动完成、开关、滑块、切换、ToggleGroup、按钮 * `references/components-panels.md` \- 手风琴、可折叠、选项卡、滚动区域 * `references/components-indicators.md` \- 工具栏、分隔符、进度、仪表、头像 * `references/styling.md` \- 完整的样式指南（Tailwind、CSS 模块、CSS-in-JS） * `references/animation.md` \- 动画模式（CSS 过渡、CSS 动画、Motion/JS） * `references/composition.md` \- 组合、定制和事件处理 * `references/forms-typescript.md` \- 表单集成和 TypeScript 类型模式 * `references/utilities.md` \- CSPProvider、DirectionProvider、mergeProps、useRender * `references/accessibility.md` \- 辅助功能、键盘导航、焦点管理、ARIA

基本用户界面指南

包含技能