docs(ui): expand bilingual component guides

2026-09-21 17:27:45 +08:00
parent fb985edb20
commit 4c61e79d0d
22 changed files with 1636 additions and 192 deletions
@@ -1,30 +1,101 @@
 ---
-title: 选择组件
-description: 按职责选择基础组件，而不是导入一个庞大的统一组件入口。
+title: 组件目录
+description: 按职责查找组件入口，并理解本地 Base UI 的组合方式。
 order: 11
 toc:
-  - id: forms
-    title: 表单与输入
-  - id: overlays
-    title: 浮层与菜单
-  - id: content
+  - id: composition-model
+    title: 组合模型
+  - id: actions-and-forms
+    title: 操作与表单
+  - id: overlays-and-navigation
+    title: 浮层与导航
+  - id: content-and-feedback
    title: 内容与反馈
+  - id: layout-and-data
+    title: 布局与数据
  - id: icons
    title: 图标
 ---

-## 表单与输入 {#forms}
+## 组合模型 {#composition-model}

-普通表单可使用 `Button`、`Input`、`Textarea`、`Field` 和 `Label`。选择类输入可加入 `Checkbox`、`RadioGroup`、`Switch` 或 `Slider`；更丰富的选择场景可使用 `Select`、`Combobox`、`Command` 或 `Calendar`。
+组件采用 shadcn/ui 的“复制源码并组合 primitives”模型，但本仓库选择的是 Base UI 实现。组件通常由 Root、Trigger、Content、Item 等部分组成，状态和可访问性由底层 primitive 管理，外观通过 Tailwind class 与 `data-slot` 暴露。

-## 浮层与菜单 {#overlays}
+Base UI 使用 `render` 组合自定义元素，而不是 Radix 版本常见的 `asChild`：

-`Dialog`、`AlertDialog`、`Sheet` 和 `Drawer` 用于模态界面。`Popover`、`HoverCard` 和 `Tooltip` 用于锚定式信息展示，菜单模块则覆盖上下文菜单、下拉菜单、菜单栏和导航模式。
+```tsx
+import { Button } from "@workspace/ui/components/button"
+import { Dialog, DialogTrigger } from "@workspace/ui/components/dialog"

-## 内容与反馈 {#content}
+;<Dialog>
+  <DialogTrigger render={<Button variant="outline" />}>编辑资料</DialogTrigger>
+</Dialog>
+```

-卡片、列表项、表格、图表、进度条、骨架屏、加载器、空状态、消息和 Toast 构成通用展示词汇。Accordion、Collapsible、Tabs、Carousel 和 Pagination 用于组织更大规模的内容。
+只在需要替换底层元素时使用 `render`。普通内容直接作为 children 传入。
+
+## 操作与表单 {#actions-and-forms}
+
+| 目标           | 组件入口                                           |
+| -------------- | -------------------------------------------------- |
+| 按钮与成组操作 | `button`、`button-group`、`toggle`、`toggle-group` |
+| 文本输入       | `input`、`textarea`、`input-group`、`input-otp`    |
+| 字段结构       | `field`、`label`                                   |
+| 布尔与单选     | `checkbox`、`switch`、`radio-group`                |
+| 范围与进度     | `slider`、`progress`                               |
+| 选项与命令     | `native-select`、`select`、`combobox`、`command`   |
+| 日期           | `calendar`                                         |
+
+简单、移动端优先且不需要自定义浮层的选项优先用 `NativeSelect`。需要搜索、多选或自定义项时，分别选择 `Combobox`、`Select` 或 `Command`。
+
+## 浮层与导航 {#overlays-and-navigation}
+
+| 目标           | 组件入口                                                 |
+| -------------- | -------------------------------------------------------- |
+| 模态确认与编辑 | `alert-dialog`、`dialog`、`sheet`、`drawer`              |
+| 锚定内容       | `popover`、`hover-card`、`tooltip`、`anchored-surface`   |
+| 菜单           | `dropdown-menu`、`context-menu`、`menubar`               |
+| 页面导航       | `breadcrumb`、`navigation-menu`、`pagination`、`sidebar` |
+
+Dialog、Sheet 与 Drawer 都提供受控状态和组合部件。重要破坏性操作使用 `AlertDialog`，短暂说明使用 `Tooltip`，需要交互控件的锚定面板使用 `Popover`。
+
+## 内容与反馈 {#content-and-feedback}
+
+| 目标       | 组件入口                                              |
+| ---------- | ----------------------------------------------------- |
+| 容器与状态 | `card`、`item`、`empty`、`alert`、`badge`、`marker`   |
+| 加载与通知 | `skeleton`、`spinner`、`toast`                        |
+| 消息界面   | `message`、`bubble`、`attachment`、`message-scroller` |
+| 分段内容   | `accordion`、`collapsible`、`tabs`、`carousel`        |
+
+`Message` 负责参与者、对齐和元数据；`Bubble` 负责消息正文表面；`Attachment` 表达上传生命周期；`MessageScroller` 管理自动跟随和回到底部按钮。它们都是展示原语，不拥有会话数据。
+
+## 布局与数据 {#layout-and-data}
+
+| 目标     | 组件入口                                                |
+| -------- | ------------------------------------------------------- |
+| 数据展示 | `table`、`chart`                                        |
+| 布局     | `separator`、`aspect-ratio`、`resizable`、`scroll-area` |
+| 方向     | `direction`                                             |
+| 键盘提示 | `kbd`                                                   |
+| 头像     | `avatar`                                                |
+
+图表模块封装 Recharts 的容器、Tooltip、Legend 与样式映射，不替应用决定数据模型。`DirectionProvider` 直接转发 Base UI 的方向上下文；页面仍应同步设置 HTML 的 `dir` 属性。

 ## 图标 {#icons}

-从 `@workspace/ui/components/icon` 导入具名图标。该模块统一了 `@icones/react` 的图标词汇，使应用和各个包使用同一图标来源。
+从本地 Icones 适配层导入具名图标：
+
+```tsx
+import { SearchIcon, SettingsIcon } from "@workspace/ui/components/icon"
+```
+
+组件会为没有显式尺寸 class 的 SVG 提供默认尺寸。图标按钮仍要提供可访问名称：
+
+```tsx
+<Button size="icon" aria-label="搜索">
+  <SearchIcon aria-hidden="true" />
+</Button>
+```
+
+不要在新组件中重新引入 `lucide-react`；需要新增图标时，在 `components/icon.tsx` 中用 `createIcon` 统一注册。