# Naive UI → Arco Design Vue 组件映射表

Phase 005 起，新代码与迁移代码一律使用 Arco Design Vue。本文表是迁移的唯一映射依据：
**先查表，再改代码**。表中没有的组件，先在此表补一行再动手。

- 全局注册：`main.ts` 全量 `app.use(ArcoVue)`，不做按需引入
- 主题：`body[arco-theme='dark']`（见 `styles/arco-theme.ts` 与 `docs/ui-baseline.md`）
- hooks：`useMessage` / `useDialog` / `useNotification` 适配层在 `packages/client/src/composables/`，
  签名冻结，**不得**在页面里直接 import Arco 的 `Message` / `Modal` / `Notification`

## Provider / hooks

| Naive | Arco | 备注 |
|---|---|---|
| `NConfigProvider` | 直接用 `body[arco-theme]` | 不需要组件 |
| `NMessageProvider` / `useMessage` | `composables/useMessage.ts` | 适配层，签名冻结 |
| `NDialogProvider` / `useDialog` | `composables/useDialog.ts` | `positiveText→okText`、`onPositiveClick→onBeforeOk`（resolve false / reject → 保持打开）由适配层转换 |
| `NNotificationProvider` / `useNotification` | `composables/useNotification.ts` | `description→content` 由适配层转换 |

## 基础组件（按当前仓库用量排序）

| Naive | Arco | 用量 | 备注 |
|---|---|---|---|
| `NButton` | `a-button` | 732 | `block`→`long`、`size="tiny"`→`size="mini"`、`type="warning"`→`type="primary" status="warning"`、`quaternary`→`status="secondary"` |
| `NInput` | `a-input` / `a-textarea` | 160 | `type="textarea"` 用独立 `a-textarea`；`a-input` 关闭了 attrs 透传，`autofocus` 无效，需 `ref` + `focus()` |
| `NModal` | `a-modal` | 138 | `v-model:show`→`v-model:visible`；`preset="dialog"` 无对应，信息型弹窗用 `:footer="false"`（`footer` 为 Boolean prop，默认 true） |
| `NFormItem` | `a-form-item` | 136 | 校验规则 API 不同（`rules` 结构、`required` 表达式）需适配 |
| `NSelect` | `a-select` | 97 | `options` 的 `label/value` 语义一致；`consistent-menu-width` 等 prop 无对应 |
| `NSpin` | `a-spin` | 86 | `show`→`loading` |
| `NTooltip` | `a-tooltip` | 76 | `trigger="hover"` 默认一致；`placement` 语义基本一致 |
| `NTag` | `a-tag` | 57 | `bordered` prop 存在（默认 true）；`size="small"` 一致；naive `type="info"`→`color="arcoblue"` 等内建色（`red/orange/green/arcoblue/...`），自定义色用 `color` 传 CSS 颜色 |
| `NSwitch` | `a-switch` | 53 | `value`/`v-model` 一致 |
| `NSpace` | `a-space` | 51 | `size` 语义一致（数字/预设名） |
| `NInputNumber` | `a-input-number` | 43 | `min`/`max`/`precision` 一致 |
| `NPopconfirm` | `a-popconfirm` | 36 | `positive-text`→`ok-text`；`@positive-click`→`@ok` |
| `NForm` | `a-form` | 32 | 校验规则 API 不同，需适配 |
| `NTabPane` | `a-tab-pane` | 30 | `NTabs/NTabPane` → `a-tabs/a-tab-pane` |
| `NDrawer` / `NDrawerContent` | `a-drawer` | 27 | Arco 无独立 content 组件；`footer` slot 用 `a-drawer` 的 `footer` |
| `NDropdown` | `a-dropdown` | 25 | `options` 结构不同（`label`→`content`，需转换函数） |
| `NDescriptions` / `NDescriptionsItem` | `a-descriptions` / `a-descriptions-item` | 19 | 基本一致 |
| `NAlert` | `a-alert` | 19 | `type` 一致；`show-icon` 一致 |
| `NRadioButton` / `NRadioGroup` / `NRadio` | `a-radio`（`type="radio-button"`）/ `a-radio-group` | 32 | Arco radio-button 是 `a-radio` 的 `type` prop |
| `NCheckbox` / `NCheckboxGroup` | `a-checkbox` / `a-checkbox-group` | 17 | `options` 数组语义一致 |
| `NEmpty` | `a-empty` | 12 | 基本一致 |
| `NCollapse` / `NCollapseItem` | `a-collapse` / `a-collapse-item` | 24 | `arrow` 语义不同 |
| `NUpload` | `a-upload` | 9 | `file-list` 结构不同，需适配 |
| `NText` | `<a-typography>` / 原生 `span` | 8 | 多数场景直接用原生元素 + class |
| `NTabs` | `a-tabs` | 6 | 见 NTabPane 行 |
| `NBreadcrumb` / `NBreadcrumbItem` | `a-breadcrumb` / `a-breadcrumb-item` | 8 | 基本一致 |
| `NDataTable` | `a-table` | 4 | **列定义 API 差异最大**（`columns`/`render`/`slots`），逐例处理 |
| `NSlider` | `a-slider` | 3 | 基本一致 |
| `NScrollbar` | `a-scrollbar` | 3 | Arco 全局可用，无需组件包裹注册 |
| `NPopselect` | `a-select`（`trigger-element`） | 3 | 无直接对应，改用 `a-dropdown` 或带 trigger 的 `a-select` |
| `NPopover` | `a-popover` | 3 | `trigger` 语义有差异 |
| `NIcon` | `<icon-*>`（`@arco-design/web-vue/es/icon`） | 3 | Arco 图标是独立组件，需 import |
| `NBadge` | `a-badge` | 3 | `value`→`count` |
| `NTree` | `a-tree` | 2 | 结构差异大，逐例处理 |
| `NCard` | `a-card` | — | 当前仓库未直接使用；若出现按此映射 |
| `NProgress` | `a-progress` | — | 当前仓库未直接使用；若出现按此映射 |
| `NLayout` / `NLayoutSider` | `a-layout` / `a-layout-sider` | — | 当前仓库未使用（侧栏是手写 div），保持手写或按需引入 |

## 迁移批次（Phase 006/007 使用）

- Phase 006：聊天页（`components/hermes/chat/`）——消息气泡内部**不用** Arco 组件（性能红线）
- Phase 007：其余视图 + `stores/` + `composables/` 批量替换 + 删除 naive-ui 依赖