Base UI

Base UI 是 MUI 的无样式 React 组件库 (@base-ui-components/react)，提供了一套高质量、可访问、可组合的 UI 组件和工具。本 skill 提供完整的 API 文档、组件参考和最佳实践指南。

快速开始

当使用 Base UI 时，按以下流程操作：

•搜索组件 - 使用搜索脚本查找所需组件
•查阅文档 - 阅读组件的完整 API 文档和使用示例
•参考指南 - 查看 Handbook 了解样式、动画、组合等最佳实践

搜索组件

使用搜索脚本快速查找组件和文档：

bash

# 搜索关键词（支持中文和英文）
python scripts/search.py <query>

# 示例
python scripts/search.py button
python scripts/search.py 表单
python scripts/search.py dialog

# 列出所有组件
python scripts/search.py --list

# 列出指定类别的组件
python scripts/search.py --cat components
python scripts/search.py --cat handbook

组件分类

表单组件 (Form Components)

用于构建表单和收集用户输入的组件：

•Form - 带有整合错误处理的表单组件
•Field - 为表单控件提供标签和验证
•Fieldset - 带有可轻松样式化图例的字段集
•Input - 输入框组件
•Checkbox - 复选框组件
•Checkbox Group - 为一系列复选框提供共享状态
•Radio - 单选按钮组件
•Number Field - 带有增减按钮的数字字段
•Select - 下拉选择器
•Combobox - 输入与预定义项列表组合
•Autocomplete - 带有过滤选项列表的自动完成输入
•Switch - 开关组件
•Slider - 滑块组件
•Toggle - 两态按钮
•Toggle Group - 切换按钮组

导航组件 (Navigation Components)

用于构建导航和菜单的组件：

•Menu - 下拉菜单，增强键盘导航
•Menubar - 应用程序的菜单栏
•Navigation Menu - 网站导航菜单
•Tabs - 标签页组件

反馈组件 (Feedback Components)

用于显示信息和状态的组件：

•Dialog - 对话框/模态框
•Alert Dialog - 警告对话框
•Popover - 弹出框
•Tooltip - 工具提示
•Toast - 通知提示
•Progress - 进度条
•Meter - 仪表组件（显示数值）
•Preview Card - 链接悬停时的预览卡片

布局组件 (Layout Components)

用于布局和分隔的组件：

•Separator - 分隔符组件
•Scroll Area - 自定义滚动条容器
•Toolbar - 工具栏

展开组件 (Disclosure Components)

用于显示/隐藏内容的组件：

•Accordion - 手风琴（可折叠面板）
•Collapsible - 可折叠组件

其他组件 (Other Components)

•Avatar - 头像组件
•Context Menu - 右键上下文菜单

Handbook 指南

Base UI 的最佳实践和高级用法指南：

Styling (样式)

了解如何使用首选样式引擎为 Base UI 组件设置样式，包括 CSS、CSS-in-JS、Tailwind 等。

文档位置: references/base-ui-docs/handbook/styling.md

Animation (动画)

学习如何为 Base UI 组件添加动画效果，包括过渡、关键帧动画等。

文档位置: references/base-ui-docs/handbook/animation.md

Composition (组合)

了解如何将 Base UI 组件与自定义 React 组件组合使用，构建更复杂的 UI。

文档位置: references/base-ui-docs/handbook/composition.md

Customization (自定义)

学习如何自定义 Base UI 组件的行为，包括事件处理、状态管理等。

文档位置: references/base-ui-docs/handbook/customization.md

TypeScript

TypeScript 使用指南，包括类型定义、泛型、类型推断等。

文档位置: references/base-ui-docs/handbook/typescript.md

工具函数 (Utilities)

Direction Provider

为 Base UI 组件启用 RTL（从右到左）行为的方向提供者。

文档位置: references/base-ui-docs/utils/direction-provider.md

useRender

在自定义组件中启用渲染属性的钩子。

文档位置: references/base-ui-docs/utils/use-render.md

概述文档 (Overview)

•
Quick Start - 快速入门指南
- •文档位置: references/base-ui-docs/overview/quick-start.md
•
Accessibility - 无障碍访问功能和指南
- •文档位置: references/base-ui-docs/overview/accessibility.md
•
Releases - 各版本的更新日志
- •文档位置: references/base-ui-docs/overview/releases.md
•
About Base UI - 库的历史、团队和目标概述
- •文档位置: references/base-ui-docs/overview/about.md

使用示例

查找组件 API

当用户询问某个组件的 API 时：

•使用搜索脚本查找组件
•读取对应的文档文件
•提供完整的 API 说明和示例

示例：

bash

# 查找 Dialog 组件
python scripts/search.py dialog

# 读取文档
cat references/base-ui-docs/components/dialog.md

实现组件功能

当用户要求实现某个组件功能时：

•搜索并找到相关组件
•查阅文档了解 props 和用法
•参考 Handbook 了解最佳实践
•提供完整的实现代码

样式自定义

当用户需要自定义组件样式时：

•查阅组件文档的样式部分
•参考 handbook/styling.md 了解样式方法
•根据用户使用的样式框架提供相应方案

核心特性

无障碍访问 (Accessibility)

Base UI 组件内置了完整的无障碍访问支持，遵循 WAI-ARIA 最佳实践。所有组件都支持键盘导航、屏幕阅读器等辅助技术。

可组合性 (Composition)

组件设计为高度可组合，可以轻松组合使用或与自定义组件结合。

样式无关 (Styling Agnostic)

Base UI 不强制任何样式方案，可以使用 CSS、CSS-in-JS、Tailwind 等任何样式引擎。

TypeScript 支持

完整的 TypeScript 类型定义，提供类型安全和优秀的开发体验。

文档结构

code

references/base-ui-docs/
├── overview/           # 概述文档
│   ├── quick-start.md
│   ├── accessibility.md
│   ├── releases.md
│   └── about.md
├── handbook/          # 指南文档
│   ├── styling.md
│   ├── animation.md
│   ├── composition.md
│   ├── customization.md
│   └── typescript.md
├── components/        # 组件文档（34个组件）
│   ├── accordion.md
│   ├── alert-dialog.md
│   ├── autocomplete.md
│   └── ...（更多组件）
└── utils/            # 工具函数
    ├── direction-provider.md
    └── use-render.md

最佳实践

•优先使用 Base UI 组件 - 而不是手动实现，以获得内置的无障碍访问功能
•遵循组合模式 - 使用组件的组合 API 而不是覆盖内部实现
•保持样式独立 - 使用 className 或 style props 而不是修改组件内部样式
•测试无障碍访问 - 使用屏幕阅读器和键盘导航测试组件
•参考 Handbook - 在实现复杂功能前，先查看相关的 Handbook 指南