---
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` 统一注册。