Maofeng
102 lines
4.8 KiB
Plaintext
102 lines
4.8 KiB
Plaintext
---
|
||
title: 组件目录
|
||
description: 按职责查找组件入口，并理解本地 Base UI 的组合方式。
|
||
order: 11
|
||
toc:
|
||
- 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: 图标
|
||
---
|
||
|
||
## 组合模型 {#composition-model}
|
||
|
||
组件采用 shadcn/ui 的“复制源码并组合 primitives”模型，但本仓库选择的是 Base UI 实现。组件通常由 Root、Trigger、Content、Item 等部分组成，状态和可访问性由底层 primitive 管理，外观通过 Tailwind class 与 `data-slot` 暴露。
|
||
|
||
Base UI 使用 `render` 组合自定义元素，而不是 Radix 版本常见的 `asChild`：
|
||
|
||
```tsx
|
||
import { Button } from "@workspace/ui/components/button"
|
||
import { Dialog, DialogTrigger } from "@workspace/ui/components/dialog"
|
||
|
||
;<Dialog>
|
||
<DialogTrigger render={<Button variant="outline" />}>编辑资料</DialogTrigger>
|
||
</Dialog>
|
||
```
|
||
|
||
只在需要替换底层元素时使用 `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}
|
||
|
||
从本地 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` 统一注册。
|