# Apollo Design

> Independent Vue 3 native UI library. Use Apollo's documented APIs, not assumptions from React or other UI libraries.

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15

Import tokens before component CSS: `@apollo-design/theme/tokens.css`, then `@apollo-design/ui/style.css`.

# 快速开始

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/guide/getting-started

Apollo Design 是独立发展的 **Vue 3 + TypeScript 原生组件库**，以公开 API、真实使用场景和一致的设计语言演进，提供静态 CSS 与 CSS 变量主题方案。

### 环境要求

- Vue **3.5+**（Composition API）
- TypeScript 5.x（推荐）
- 现代浏览器（ES2022）

### 安装

```bash
npm install @apollo-design/ui @apollo-design/theme vue
```

图标按需安装 `@apollo-design/icons`。使用 AI 编程助手时，可参考 [AI 接入](https://apollocmh.github.io/apollo-design-ui/guide/ai) 获取当前版本的 API 与示例。

### 引入

```ts
import { createApp } from 'vue';
import App from './App.vue';

// ① 设计令牌（零运行时 CSS 变量，必须最先引入）
import '@apollo-design/theme/tokens.css';
// ② 全量组件样式
import '@apollo-design/ui/style.css';

createApp(App).mount('#app');
```

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <Space>
    <Button type="primary">主按钮</Button>
    <Button>默认按钮</Button>
  </Space>
</template>
```

### 下一步

- [样式引入](https://apollocmh.github.io/apollo-design-ui/guide/styles) —— tokens.css 与组件样式的关系
- [按需使用](https://apollocmh.github.io/apollo-design-ui/guide/tree-shaking) —— ESM tree-shaking
- [主题](https://apollocmh.github.io/apollo-design-ui/guide/theming) —— 亮暗切换与 token 定制
- [国际化](https://apollocmh.github.io/apollo-design-ui/guide/i18n) —— ConfigProvider 与内置语言包



---

# AI 接入

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/guide/ai

AI 编程助手需要先读取 Apollo Design 的文档，再生成代码。Apollo 是独立发展的 Vue 3 原生组件库，不能直接套用 React 或其他组件库的 API。

### 把文档交给 AI

- [llms.txt：文档索引](https://apollocmh.github.io/apollo-design-ui/llms.txt)
- [llms-full.txt：完整中文文档与示例](https://apollocmh.github.io/apollo-design-ui/llms-full.txt)
- [llms-full.en.txt：完整英文文档与示例](https://apollocmh.github.io/apollo-design-ui/llms-full.en.txt)
- [Button 单组件 Markdown](https://apollocmh.github.io/apollo-design-ui/components/button.md)

每个组件都有 `components/<name>.md` 和 `components/<name>.en.md`，指南有 `guide/<slug>.md` 和 `guide/<slug>.en.md`。完整文件可能超过模型上下文，日常优先使用索引和单页。静态文件跟随文档站部署更新，开头标注 UI 版本与源码提交；使用旧版本项目时需核对版本。

可以把这段要求放进项目的 AI 指令文件：

```text
本项目使用 Apollo Design（Vue 3）。编码前核对已安装的 @apollo-design/ui 版本，
读取 https://apollocmh.github.io/apollo-design-ui/llms.txt 中对应组件的文档和示例。
Props、Slots、Emits、v-model 和导入方式以 Apollo 文档为准，不推测其他 UI 库的 API。
先引入 @apollo-design/theme/tokens.css，再引入 @apollo-design/ui/style.css。
缺少 API 信息时先查询；不要编造属性、事件或包名。
```

这些文件用于提供上下文。AI 客户端不一定自动发现或读取 `llms.txt`，需要在提示词或项目指令中明确提供链接。

### 本地 MCP

`@apollo-design/mcp` 提供 stdio MCP 服务，文档随包携带，查询时无需网络、账号、API Key 或在线服务器。通过 npm 分发，选择与项目 UI 相同的版本（当前为 `0.1.9`）。首次使用 `npx` 会下载包，后续查询直接读取随包文档。

```bash
npx -y @apollo-design/mcp@0.1.9 --project /absolute/path/your-vue-project
```

在支持 MCP 的客户端中加入配置，替换项目绝对路径（不同客户端配置文件位置可能不同）：

```json
{
  "mcpServers": {
    "apollo-design": {
      "command": "npx",
      "args": [
        "-y",
        "@apollo-design/mcp@0.1.9",
        "--project",
        "/absolute/path/your-vue-project"
      ]
    }
  }
}
```

需要 Node.js 22.12+。`--project` 指向已安装 `@apollo-design/ui` 的应用目录；服务启动时核对精确版本，不匹配或无法解析该包会报错。省略该参数可浏览随包文档，但会明确标记项目版本未验证。

四个只读工具：`search_components` 搜索组件和指南，`get_document` 获取 API 或指南，`list_examples` 列出示例，`get_example` 获取真实 Vue 源码及本地辅助文件。工具不执行示例、不修改项目；文档、源码、公开导入路径与网站使用同一条生成链路。



---

# 样式引入

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/guide/styles

Apollo Design 使用静态 CSS 与 CSS 变量。JS 导入不会自动安装样式；构建期 resolver、手工子路径和全量导入使用同一主题 API，主题选择与组件按需引入互不依赖。

| 资源 | 职责 |
| --- | --- |
| `@apollo-design/theme/presets/mono.css`（或 default/material3） | 可选的独立公共变量表，包含该风格的 light/dark/system 作用域；由公开派生 API 生成 |
| `@apollo-design/ui/base.css` | 不选择主题的共享基础结构规则 |
| `@apollo-design/ui/<component>/structure.css` | 单一组件结构规则；依赖资源按公开 style-manifest 顺序加载 |
| `@apollo-design/ui/<component>/style.css` | 保留的自包含组件样式，包含内部实现依赖；不要与同组 structure.css 重复引入 |
| `@apollo-design/ui/style.css` | 保留的全量组件样式 |
| `@apollo-design/theme/tokens.css` | 保留的默认亮/暗/紧凑变量表；选择独立预设时不需要同时加载它 |

### 自动按需

以下结构资源与官方 resolver 要求 UI 0.1.8 或更高版本。

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import Components from 'unplugin-vue-components/vite';
import { ApolloResolver } from '@apollo-design/ui-resolver';

export default defineConfig({
  plugins: [vue(), Components({ resolvers: [ApolloResolver()] })],
});
```

```vue
<!-- App.vue -->
<script setup lang="ts">
import { monoPreset } from '@apollo-design/theme/presets/mono';
import '@apollo-design/theme/presets/mono.css';
const theme = { preset: monoPreset, mode: 'system' as const };
</script>

<template>
  <AConfigProvider :theme="theme">
    <AButton type="primary">Mono</AButton>
  </AConfigProvider>
</template>
```

resolver 只从公开子路径导入组件 JS 与结构 CSS，不选择主题，也不引入全量 CSS。它按 `@apollo-design/ui/style-manifest.json` 导入共享基础、依赖与组件结构，重复路径由打包器去重；生成的组件声明需纳入项目 TypeScript 配置。保留已有全量/自包含 CSS 的应用应设 `ApolloResolver({ importStyle: false })`，避免同时引入重叠规则。

### 手工子路径

同一个配置可以手工引入，无需 resolver：

```vue
<script setup lang="ts">
import { ConfigProvider } from '@apollo-design/ui/config-provider';
import { Button } from '@apollo-design/ui/button';
import { monoPreset } from '@apollo-design/theme/presets/mono';
import '@apollo-design/theme/presets/mono.css';
import '@apollo-design/ui/base.css';
import '@apollo-design/ui/button/structure.css';
const theme = { preset: monoPreset, mode: 'system' as const };
</script>

<template>
  <ConfigProvider :theme="theme"><Button type="primary">Mono</Button></ConfigProvider>
</template>
```

Button 的最小结构依赖如上；复杂组件按公开 style-manifest 的完整 styles 列表加载，或使用原有 `ui/<component>/style.css` 自包含入口。用户插槽中的自选组件仍需自己的 CSS。AutoComplete 使用 Select 结构；TimePicker/TimeRangePicker 使用 DatePicker；Layout.Sider 具有独立的 layout-sider 样式入口。ConfigProvider 本身不需要组件样式。

### 全量引入

```vue
<script setup lang="ts">
import { ConfigProvider, Button } from '@apollo-design/ui';
import { monoPreset } from '@apollo-design/theme/presets/mono';
import '@apollo-design/ui/style.css';
import '@apollo-design/theme/presets/mono.css';
const theme = { preset: monoPreset, mode: 'system' as const };
</script>

<template>
  <ConfigProvider :theme="theme"><Button type="primary">Mono</Button></ConfigProvider>
</template>
```

结构入口的推荐顺序是公共变量 → 基础/组件结构 → 用户覆盖；旧聚合或自包含样式先加载，独立预设放在其后，避免旧默认规则覆盖选择。不要在已加载整套 CSS 后再补同组结构资源。应用只需加载自己使用的一个预设；文档站为了切换预览，显式加载全部三份，不作为普通应用的隐式兜底。

### 作用域与动态配置

静态主题通过 `data-apollo-preset="default|mono|material3"` 与 `data-apollo-theme="light|dark|system"` 选择，system 在 CSS 中响应系统明暗。Provider 使用同一预设对象与 `mode` 派生当前作用域，用户全局 Token、组件 Token 与嵌套覆盖见[主题](https://apollocmh.github.io/apollo-design-ui/guide/theming)。运行时更新 CSS 变量不重挂组件，也不意味着懒加载组件。

```html
<html data-apollo-preset="mono" data-apollo-theme="system">
```

保留默认主题的旧用法仍可使用 `theme/tokens.css` → `ui/style.css`；compact/dark-compact 是该旧资源的密度作用域，不是新的风格预设。发布的组件 CSS 使用 `apollo` 前缀，自定义前缀需匹配的静态样式。站点的 `--site-*` 只引用公共主题 Token，没有独立配色表。

### 默认链接样式

共享基础层为原生链接提供当前主题的颜色、装饰与可见键盘焦点；这些默认值不依赖是否使用 Select。可以用原生 `style` 或自己的 CSS 覆盖。

### 原生表单控件

共享样式保留原生控件的浏览器前景、背景和禁用颜色。Apollo 组件使用各自的主题色；自行给原生控件设置颜色时，请同时配置背景。例如 `style="color: inherit; background: transparent"` 可让原生按钮使用父级颜色，避免暗色作用域中的浅色文字落在浏览器浅色背景上。



---

# 按需使用

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/guide/tree-shaking

Apollo Design 支持通过 `@apollo-design/ui-resolver` 自动按需引入，也支持手动导入。组件以 ESM 模块发布，打包器可以对未使用的导出做 tree-shaking；组件样式和主题变量按下面的方式加载。

### 自动按需引入

使用 `@apollo-design/ui-resolver` 配合 `unplugin-vue-components`，可以根据 Vue 模板自动引入组件及其所需的结构样式。

#### 安装

```bash
npm install @apollo-design/ui @apollo-design/theme vue
npm install -D @apollo-design/ui-resolver unplugin-vue-components
```

当前 resolver 支持 UI `>=0.1.8 <0.2.0` 和 `unplugin-vue-components ^32.1.0`，建议 Apollo 包使用相同发布版本。以下配置适用于已安装 `vite` 和 `@vitejs/plugin-vue` 的 Vue 项目。

#### 配置 Vite

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import Components from 'unplugin-vue-components/vite';
import { ApolloResolver } from '@apollo-design/ui-resolver';

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [ApolloResolver()],
      dts: 'src/components.d.ts',
    }),
  ],
});
```

将生成的 `src/components.d.ts` 纳入应用的 TypeScript 配置，例如已有的 `include: ["src/**/*.ts", "src/**/*.vue"]` 会包含它。

#### 加载主题并使用组件

在应用入口加载默认主题变量：

```ts
// main.ts
import '@apollo-design/theme/tokens.css';
```

模板中使用 `A` 前缀组件，无需在 `<script setup>` 中手动导入：

```vue
<template>
  <ASpace>
    <AButton type="primary">保存</AButton>
    <AInputSearch placeholder="搜索" />
  </ASpace>
</template>
```

复合组件使用明确名称，例如 `AInputSearch`、`AFormItem`、`ASpaceCompact`、`ALayoutSider`。模板也可使用对应的 kebab-case，例如 `<a-button>`。

`ApolloResolver()` 默认按需加载组件及依赖的结构 CSS，重复样式路径由打包器去重；主题变量由应用选择和加载。此方式无需再引入 `@apollo-design/ui/style.css` 或同组组件的 `style.css`。选择 Mono、Material 等独立主题时，参照[样式引入](https://apollocmh.github.io/apollo-design-ui/guide/styles)与[主题](https://apollocmh.github.io/apollo-design-ui/guide/theming)配置预设。

如果项目已经全量引入样式，或希望自行管理 CSS，可关闭 resolver 的样式导入：

```ts
ApolloResolver({ importStyle: false })
```

关闭后仍会自动引入组件 JS，但应用需要自行加载所需样式。resolver 面向 Vue 模板；在脚本中调用 `message`、`notification` 等服务，或在 TSX / render 函数中使用组件时，仍需显式导入，并加载相应样式。

### 手动按需引入

手动选择组件及其自包含样式入口：

```ts
import { Button, Space, Table } from '@apollo-design/ui';
import '@apollo-design/theme/tokens.css';
import '@apollo-design/ui/button/style.css';
import '@apollo-design/ui/space/style.css';
import '@apollo-design/ui/table/style.css';
```

也可从公开子路径导入，例如 `import { Button } from '@apollo-design/ui/button'`。打包器会保留所用组件及其实际 JS 依赖；各组件的 `style.css` 包含实现内部所需的样式，插槽中由应用选择的其他组件仍需自己的样式。

### 全量样式

需要统一加载全库样式时，在应用入口引入：

```ts
import '@apollo-design/theme/tokens.css';
import '@apollo-design/ui/style.css';
```

这种方式仍可使用 JS 的命名导入与 tree-shaking；如果同时启用 resolver，请设置 `importStyle: false`，避免叠加重复样式。更多结构样式、独立预设和加载顺序见[样式引入](https://apollocmh.github.io/apollo-design-ui/guide/styles)。



---

# 主题

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/guide/theming

[打开主题展示](https://apollocmh.github.io/apollo-design-ui/guide/themes)，在同一页比较三套主题的亮暗外观。

### 风格与明暗独立选择

默认、Mono 与 Material 风格通过相同公开 API 派生。Mono 使用黑白灰、克制圆角与阴影，并保留语义色；Material 参考 MUI 的中性表面、4px 默认圆角与层级阴影，保留 Apollo 的组件交互规范。公开入口仍为 `material3`，可在[主题展示](https://apollocmh.github.io/apollo-design-ui/guide/themes)中比较亮暗效果。

```vue
<script setup lang="ts">
import { ConfigProvider, Button } from '@apollo-design/ui';
import { monoPreset } from '@apollo-design/theme/presets/mono';

const theme = {
  preset: monoPreset,
  mode: 'system' as const,
  token: { colorPrimary: '#6455ff', borderRadius: 8 },
  components: { Button: { paddingInline: 20 } },
};
</script>

<template>
  <ConfigProvider :theme="theme">
    <Button type="primary">自定义 Mono</Button>
  </ConfigProvider>
</template>
```

独立入口分别是 `@apollo-design/theme/presets/default`、`/mono`、`/material3`，具名导出为 `defaultPreset`、`monoPreset`、`material3Preset`，同时提供默认导出。根入口只导出类型与派生服务，不加载全部预设。自定义预设使用公开 `ThemePreset` 数据结构，无需向 resolver 注册。

`ThemeConfig.mode` 支持 `light | dark | system`。实时 Provider 在挂载后响应系统偏好并释放监听；纯函数 `getDesignToken(config, systemAppearance?)` 与 SSR 缺省按 light 派生，服务端已知偏好时可传第二个参数 `'dark'`。

### 覆盖顺序与嵌套边界

派生顺序为：默认种子 → 预设公共 Token → 所选明暗方案 → 用户种子覆盖并派生 → 用户 Map/Alias 最终覆盖。组件 Token 在组件作用域覆盖相应默认值。局部显式 `algorithm` 优先于继承的 `mode`；局部显式 `mode` 优先于继承的 `algorithm`。因此演示局部暗色算法的 Demo 仍保留自己的意图。

`ConfigProvider` 默认继承父级原始主题配置，`theme.inherit: false` 重置继承。独立 `ThemeProvider` 保留原有默认重置语义；要合并父级，请显式设置 `theme.inherit: true`。两者都在原始配置层合并，避免把父级派生后的颜色当成下一层种子。并排 Provider、嵌套 Provider、所属 Portal 和通过 App/上下文 API 创建的 Message/Notification 保持各自主题边界。

```vue
<ConfigProvider :theme="{ preset: monoPreset, mode: 'dark' }">
  <Button>继承 Mono 暗色</Button>
  <ConfigProvider :theme="{ token: { borderRadius: 12 } }">
    <Button>继承配色，仅覆盖圆角</Button>
  </ConfigProvider>
</ConfigProvider>
```

### 静态资源与三种引入方式

JS、组件结构 CSS 与主题选择彼此独立。参见[样式引入](https://apollocmh.github.io/apollo-design-ui/guide/styles)中的自动按需、手工子路径、全量三种入口及加载顺序。Provider 会在已有组件作用域更新 CSS 变量，不重挂组件；静态 CSS 仍需显式引入。

也可使用可选 `@apollo-design/theme/presets/default.css`、`/mono.css`、`/material3.css`。每份由同一 `getDesignToken` 公开 API 生成，含 light/dark/system 选择器，不引用另一份预设。选择器示例：

```html
<html data-apollo-preset="mono" data-apollo-theme="system">
```

自行覆盖原生 CSS 变量无需运行时，但种子变量的覆盖不会自动重算整套派生色阶；需要派生时使用 Provider 或 `getDesignToken`。同时设置前景与背景，避免暗色文字落在浅色背景上。

### 文档站实时预览

Header 的主题面板分别提供默认/Mono/Material 与浅色/深色/跟随系统。选择保存在本机，换页和刷新保留，首屏先设置同一公开属性选择器再加载样式；SSR 保留确定的默认结构，挂载后接入客户端选择。站点 `--site-*` 只引用组件公开 Token，不维护第二套调色板。

内联 Demo 继承站点选择，但其局部 Provider 可覆盖。独立链接携带初始 `preset`、`theme`、`lang`。iframe 在客户端首次创建时携带当前选择，后续以验证 origin、source、frameId 的受控消息更新，不改写 src，不丢失输入、选择与展开状态。文档站为了提供三个可选风格显式加载三份预设 CSS；只用一个风格的应用只需加载自己的入口。



---

# 主题展示

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/guide/themes

### 如何比较

上方以相同内容并排呈现 Default、Mono 和 Material，第一行为亮色，第二行为暗色。六个预览各有独立的主题作用域；切换站点外观时，预览仍保留标注的亮暗模式，便于比较色彩、圆角和控件状态。窄屏会按相同顺序折行，不必横向滚动整页。

可以直接修改名称、切换通知开关，或点击「继续」和「重置」观察进度。各个预览的状态互相独立，修改一处不会影响其他卡片。比较时也可使用 Tab 键依次访问控件，查看键盘焦点及禁用按钮的表现。

「重置」仅将进度恢复为 64；名称与通知开关保留各自的编辑状态，方便继续比较不同主题。

### 选用与定制

Default 提供默认外观，Mono 呈现单色风格，Material 参考 [MUI Material UI](https://github.com/mui/material-ui) 的中性表面、克制圆角和层级阴影。品牌色在亮暗模式中均为 **#0073E6**；填充操作的悬停色加深，暗色文字与链接使用更明亮的颜色。保留 `material3Preset` / `material3` 的公开名称，已有导入路径与主题配置无需改名。应用接入、自定义品牌、明暗切换与嵌套作用域的具体配置，请阅读[主题使用与定制](https://apollocmh.github.io/apollo-design-ui/guide/theming)；此页用于比较真实组件效果。



---

# 国际化

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/guide/i18n

组件内置文案（空状态、分页、确认弹窗等）通过 `@apollo-design/locale` 提供：

```vue
<script setup lang="ts">
import { ConfigProvider } from '@apollo-design/ui';
import { zh_CN } from '@apollo-design/locale';
import { ref } from 'vue';

const locale = ref(zh_CN);
</script>

<template>
  <ConfigProvider :locale="locale">
    <RouterView />
  </ConfigProvider>
</template>
```

- 内置几十种语言包（`zh_CN` / `en_US` / `ja_JP` / …），采用稳定的语言与地区标识。
- `useLocale('Table')` 等按组件名称读取本地文案和语言代码，返回两个响应式 computed ref。
- 切换 `locale` 引用即全局生效，无需重新挂载。

### 本文档站

站点自身的界面文案（导航、工具栏、搜索提示等）是独立的一套词典，右上角切换中 / 英；组件文档在中英两份内容间切换，缺失英文译文时**明确回退到中文并给出提示**，不静默混排。



---

# 兼容性说明

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/guide/compatibility

## 兼容对象

Apollo 对自身公开 API、文档化行为、类型、语义样式接口和实际用户负责。Ant Design 不是唯一规格，不绑定 Apollo 的发布版本，也不要求组件/API/Token/DOM 数量相同。默认保留已有合理行为与视觉。

## 保留的边界

- 已有组件导出、props、事件 payload、`v-model` 名称、expose、令牌和样式入口默认保持兼容；开发阶段模板扩展 API 按 ADR 0006 直接迁移；为保留 React 回调/DOM 形态而妨碍 Vue 公共用法的行为按 ADR 0007 直接修正。
- 根节点使用 Vue `class` / `style`；先前已经完成的根别名迁移不回滚。非根 `classNames.*` / `styles.*` 和现存 deprecated alias 保留各组件已文档化行为。
- 同名 ConfigProvider 配置字段、数据项字段和组件 attrs 不等同，不因名称类似 React 而删除。
- 现有 VNode 数据和命令式服务按职责保留。组件顶层内容渲染函数 prop 直接替换为具名/作用域插槽，不保留函数兼容层或弃用期（用户裁决、ADR 0006）；逐组件同步实现、类型、调用者、文档与测试。数据项渲染字段另行按实际契约评估。迁移不得破坏数字动画、缓存或业务 payload。
- `prefixCls` 的 DOM 响应性需要保证，但现有静态 CSS 不自动支持任意前缀。完整前缀样式策略继续追踪 KNOWN-ISSUES 的 D04。
- `middle` 等既有值、子组件别名和已验收视觉不为独立化重新命名。

## 变更分类与迁移

错误实现 → 用场景与契约证明后修复；有意设计改变 → 记录理由、影响、类型、示例和回归；环境差异 → 记录平台与复现条件；上游差异 → 可作参考，不自动构成缺陷或豁免。

破坏性公共 API 必须单独记录：旧/新写法、受影响版本、替代方案、弃用期、运行时及类型兼容层、移除条件、验证命令。当前 `0.1.x` 未发布开发阶段，用户已授权模板扩展 API 直接迁移；这类变更记录旧/新写法与测试证据，兼容层和弃用期明确为无，无需逐组件重复申请批准。用户另已授权按 ADR 0007 直接修正牺牲 Vue 公共用法的 React 回调/DOM 兼容：不保留错误载荷或树形态的兼容层/弃用期；逐组件记录影响与验证。其他破坏性变更仍单独评审。

Vue 公共语义与 React 回调/DOM 冲突的直接修正规则见 [ADR 0007](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/adr/0007-vue-public-contracts-over-react-shapes.md)。已批准的模板扩展迁移见 [ADR 0006](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/adr/0006-development-template-slots.md)，Transfer 首批变化见 [迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/transfer-slots.md)。Alert / Collapse 已有内容插槽的优先级调整另见 [行为迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/content-slot-precedence.md)。List 的 `renderItem` → 泛型 `#item`、内容插槽及废弃告警调整见 [List 迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/list-slots.md)。其他待评估事项见 [独立化记录](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/independence.md)，未裁决事项不算已批准。

Typography 的固定标签类型、Link 原生操作树、编辑/复制/测量、有效 Token 和关联 Table 主题变量修正见 [Typography 契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/typography-contracts.md)。

Badge / Ribbon 的原生根 style/ref、完整 text 内容/槽、当前配置与九 Token、数字/偏移及可读前景修正见 [Badge 契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/badge-contracts.md)；直接修正开发期错误落点，原二十六场景和参考证据保留。

## 上游参考与历史回归

List 当前配置、稳定内容结构、嵌套样式与分页修正，以及共享 `RenderEmptyHandler` 类型收窄，集中见 [List 契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/list-contracts.md)。

共享reset的原生控件颜色配对修正见 [颜色迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/native-control-colors.md)。Spin全屏模式保留正文文档流，root为内容外壳，mask为实际覆盖层；相关落点变更与验证也见List契约迁移。

Spin的完整Vue内容、显式indicator scope、稳定section/indicator、SSR确定进度（含0）与4个有效Token集中见 [Spin契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/spin-contracts.md)。这按ADR0007直接修正旧DOM/首帧形态，不恢复已移除indicator prop或增加兼容通道。

QRCode的statusRender直接替换为#status、稳定refresh事件操作、根/图像样式拥有关系、默认白色宿主与可访问名称、当前遮罩Token和语言，集中见 [QRCode契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/qrcode-contracts.md)。原编码引擎与合法输入的矩阵/路径保留。

`tests/compat`、Oracle 与 `tests/visual/baselines/react` 保留来源版本以便复现；版本固定只约束这组参考实验。上游对照默认不决定新组件完成或发布验收。现有 DOM 回归测试仍执行，必要差异必须根据 Apollo 契约审查，不允许无依据放宽。

## 9. 历史差异登记

`image-optional-alt-accessible-name`：Image省略alt时，实际img使用空替代文本；预览触发器使用“Preview image”，弹层使用“Image preview”作为通用名称，避免公开可选prop产生无名称控件。旧React对照缺少触发器名称的5个场景保留，精确断言仅此差异，并以Apollo原生回归及实际浏览器axe验证。集中迁移与当前验证边界见 [Image契约修正](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/image-contracts.md)。

原 D 编号及逐组件迁移证据完整保存在 [2026-10 历史兼容记录](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/history/compatibility-2026-10.md)。旧链接/脚本引用该表时按历史记录解释；其中的 Phase、逐字同构和强制对拍要求已被本文取代。不要删除已有问题复现或第三方来源说明。

Statistic/Timer/Countdown的原生#value业务作用域、当前计时方向/非负事件、SSR/清理、attrs/ref及两字号Token修正集中见[Statistic契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/statistic-contracts.md)；不新增旧内容函数兼容层。

Skeleton及五个子组件的原生根attrs/style、嵌套块配置、Image默认槽、当前八Token和装饰占位语义修正集中见[Skeleton契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/skeleton-contracts.md)；直接修正开发期错误形态，不新增兼容通道。

Result全部状态的完整图标槽/默认图形开关、条件内容、原生根attrs/style、当前Provider/四Token和装饰语义修正集中见[Result契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/result-contracts.md)；开发期直接修正，不为旧React图形分支增加兼容通道。

Button完整内容宿主、独立color/variant、加载请求与指示器分离、当前Provider/58 Token及合法发布工具入口修正见[Button契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/button-contracts.md)；内部Search/Dropdown/FloatButton链路同步调整。

Empty 的完整 image/description/footer 内容、当前 Provider/语言、自然布局、空宿主及默认文字对比度修正见 [Empty 契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/empty-contracts.md)；保留插画几何与原始参考证据。

Tag / CheckableTag / CheckableTagGroup 的完整内容、所属原生关闭按钮/链接、Vue 事件和强类型模型、当前 Provider/三个 Token 与两套真实语义，集中见 [Tag 契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/tag-contracts.md)；原始参考矩阵保留，开发期直接修正错误 DOM/回调形态。

Avatar / AvatarGroup 的原生事件与同步取消钩子、完整内容槽、当前尺寸/Token、业务key和溢出按钮，集中见 [Avatar契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/avatar-contracts.md)；直接移除四个分组旧别名，保留原始参考证据。

### D-typography-native-controls

开发阶段按 ADR0007 直接修正 Link 的 span/a 所属结构、text 编辑键盘入口与原生按钮内装饰图标语义。原 76 场景、参考 HTML 与参考 PNG 不变；19 个场景的精确差异存于 Typography contract-differences.ts，任何额外差异继续失败。详情与迁移见 Typography 契约迁移。

Descriptions 的稳定原生描述项、当前配置/十Token、所属attrs与label槽修正见[Descriptions契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/descriptions-contracts.md)。Timeline 的原生根事件、实际ref、完整标量内容、当前六Token与显式方向见[Timeline契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/timeline-contracts.md)。Breadcrumb 的所属内容/菜单按钮、参数、原生attrs、当前七Token与内容槽见[Breadcrumb契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/breadcrumb-contracts.md)；三单元已完成产物、正式视觉和Docs统一验收，见[四单元验收回执](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/docs/content/guide/docs/audit/evidence/four-unit-final-acceptance.json)。共享Menu Enter导航修复证据保留，完整Menu审计另行继续。

Space/Compact/Addon 的当前插槽、稳定内容身份、完整 separator 数据、紧凑上下文与主题作用域见[Space契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/space-contracts.md)；Grid/Row/Col 的原生样式、当前配置与响应式字段见[Grid契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/grid-contracts.md)。直接修正开发期错误行为，不新增内容回调兼容层；两单元已分别完成发布、视觉和Docs验收，Space关联Input窄链通过不代表完整Input API已验收。

Flex的完整内容、当前gap与原生样式见[Flex契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/flex-contracts.md)；Alert/ErrorBoundary的内容、关闭流程与Vue错误恢复见[Alert契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/alert-contracts.md)；Layout家族的原生根、当前配置与Sider受控/响应式链见[Layout契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/layout-contracts.md)。三者与Space已统一验收，证据及剩余边界见[本批最终回执](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/docs/content/guide/docs/audit/evidence/space-flex-alert-layout-final-acceptance.json)。

Theme的可写深响应式配置、同应用默认来源共享/跨应用与SSR隔离、mounted变量注入和可释放scope所有权，以及空算法/undefined覆盖、精确Alias类型和原生DOM引用target，集中见[Theme契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/theme-foundation-contracts.md)。开发期直接移除无消费的ThemeConfig.prefixCls；DOM类名沿用ConfigProvider顶层prefixCls，CSS变量名使用cssVarPrefix，不新增兼容通道。该源码里程碑不代表ConfigProvider/Tree完整单元或全库最终门禁已关闭。

共享 `useControlledValue` 的受控请求、撤控保留值与函数更新规则见[受控状态迁移](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/controlled-value.md)。开发阶段直接修正 rc 内部状态语义，不提供旧行为开关。

组件 Token 配置保留字符串、数字和布尔标量，以支持已公开的 `InputNumber.handleVisible`；不接受函数或嵌套对象。各组件仍按其字段契约消费，布尔开关不会当作其他组件的 CSS 数值。

Switch 的 Provider 样式、具名槽、原生 attrs 和真实模板 ref 类型修正见[Switch API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/switch/index.zh-CN.md)；全局 large 解析为该组件已支持的 medium，不新增尺寸能力。

十三个组件 Token 和已消费的全局别名读取当前主题，嵌套、替换和撤除均更新实际 CSS；保留原生与语义样式优先级。

### D-back-top-native-button

BackTop 改为原生 button 和完整内容槽，click 发送原生 MouseEvent，公开真实按钮引用；target 跟随当前模板 ref，并在换目标、重复点击和卸载时清理滚动动画。历史 div/首节点克隆的差异在本组件 semantic 测试中精确登记，参考基线保留。迁移见[BackTop API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/back-top/index.zh-CN.md)。

### D-rate-native-events-and-focus

Rate 的 change/hoverChange/focus/blur 使用 Vue emits，焦点事件带原始 FocusEvent；具名槽和真实实例引用保留精确类型。radio 组只保留一个已选值和一个 Tab 入口，动态 tooltip 不替换焦点项；新增可达性属性与旧前缀差异逐场景精确比较，不忽略整类属性。迁移见[Rate API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/rate/index.zh-CN.md)。

六个组件 Token 读取当前主题，嵌套、替换、撤除和全局派生及时生效；原生与语义样式继续按既有优先级覆盖。

### D-pagination-native-model-inputs

Pagination 保留既有原生插槽交付，修正受控页码/尺寸撤控、总量收缩、键盘提交、焦点归属及禁用交互。尺寸选择器使用原生 class；十二个组件 Token 与输入样式读取当前主题。精确 DOM 差异保留在 semantic 测试，参考基线不变，详见[Pagination API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/pagination/index.zh-CN.md)。

### D-input-number-native-contracts

InputNumber 的 change/step/pressEnter 统一为 Vue 事件，模板引用暴露实际元素与方法；显式 null、受控撤除、输入法、光标及异步清理遵守文档契约。当前 Provider、variant 和组件 Token 跟随配置替换或移除，详见[InputNumber API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/input-number/index.zh-CN.md)。

### D-steps-live-tokens

Steps 使用唯一 change emit，接通九个有效组件 Token。直接移除从未被组件消费的 customIconSize/customIconTop/iconTop/titleLineHeight；使用现有 iconSize/customIconFontSize 或原生样式表达受支持的定制，不新增旧字段兼容。既有四槽和 inline Tooltip 成果保留，详见[Steps API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/steps/index.zh-CN.md)。

### D-progress-live-contracts

Progress 补齐动态位置、原生样式、当前 Provider/六 Token、Circle 描边与渐变、CSS 长度宽度等已声明行为；保留 format/rounding 与现有别名。单色 inner 文字修正前景对比，语义 color 仍优先；自定义渐变和透明背景的配色边界见[Progress API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/progress/index.zh-CN.md)。Upload 已交付进度语义不变。

### D-masonry-native-layout

Masonry 的 layoutChange 使用 Vue emits，MasonryRef 与文档化 nativeElement() getter 一致；同 key 数据替换和离场资源保持正确。CSS 字符串 gutter 交由浏览器解析，纵向百分比使用文档化 intrinsic/显式高度基准，避免根高反馈循环；item.height 仍是槽和事件的数据，不新增布局提示语义。详见[Masonry API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/masonry/index.zh-CN.md)。

### D-tooltip-current-overlay

Tooltip 的 openChange/popupClick/afterOpenChange 使用 Vue emits，原生 class/style 只作用于浮层根，模板 ref 暴露真实元素属性。afterOpenChange 通知通过 Popover、Popconfirm 同链迁移为 `@after-open-change` / `onAfterOpenChange`，不保留旧回调 prop。当前主题、箭头、层级与定位跟随实际配置和尺寸更新，详见[Tooltip API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/tooltip/index.zh-CN.md)。两层包装的其余契约仍按各自进行中任务处理。

### D-float-button-native-group

FloatButton / Group 使用当前插槽、Provider 与主题别名；Group 通知改为 Vue emits，原生 attrs 只作用于根，trigger 在列表前以支持自然 Tab 顺序，Escape 在接受关闭后返回焦点。BackTop 保留当前目标并释放动画/监听，PurePanel 展示真实分支；既有样式生成器正确消费显式自定义前缀，不新增运行时 CSS。详见[FloatButton API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/float-button/index.zh-CN.md)。

### D-popover-current-owner

Popover 拥有 openChange/popupClick/afterOpenChange 的 Vue emits，继承的样式与销毁别名真实转发；自身四 Token、当前 Provider 与 PurePanel 颜色生效。包装层把当前层级基准传给 Tooltip，共享同一层级上下文，不重复叠加。真实引用、原生样式与内容插槽沿用既有成果；wireframe 的视觉缺口仍明确延期，详见[Popover API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/popover/index.zh-CN.md)。

### D-tree-native-contracts

Tree / DirectoryTree 修正受控模型、完整事件转发、原生事件载荷、实际焦点/滚动/行测量与加载和拖放资源。顶层 titleRender、icon/switcherIcon 等内容函数迁为具名作用域插槽；数据项函数按数据职责保留，TreeSelect 同步迁移实际消费桥。九个组件 Token 使用当前主题，prototype 命名键安全保留；Directory 叶子显示文件图标，历史 DOM 参考只登记精确差异。详见[Tree API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/tree/index.zh-CN.md)。

### D-mentions-current-contracts

Mentions 保留六组既有整改，补齐当前 Provider/二十一个有效组合 Token、可空容器与真实模板 ref；只读、禁用和 hidden 路由到实际拥有者。PurePanel 在自身 host 展示真实菜单。移除未消费的 Mentions addonBg 与 OptionProps.children，Option 内容使用默认槽、key 支持 string/number；Input 自己有效的 addonBg 保留。详见[Mentions API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/mentions/index.zh-CN.md)。

### D-tabs-native-contracts

Tabs 保留已交付 popup/extra 槽，修正受控撤除、同 key 面板身份、item 级销毁优先级、SSR 稳定 ARIA id 与真实 ref 属性。导航和溢出选项拥有独立的可访问树，关闭按钮保留键盘入口；当前 Provider 与二十四个有效 Token 实际消费。移除从未实现的顶层 children 与两个空 margin Token，items[].children 和 horizontalItemGutter 保留；开发版 editable 命令类型要求 remove 携带 key。详见[Tabs API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/tabs/index.zh-CN.md)。

### D-upload-native-contracts

Upload / Dragger 修正文件预处理替换、请求/移除竞态、受控列表与取消、预览资源释放，统一原生 attrs、插槽、真实引用及当前 Provider/Token。beforeUpload=false 的 change 文件统一为 UploadFile，通过 originFileObj 读取原文件；自定义请求收到实际文件与默认请求服务。删除无消费的 supportServerRender/styleAttrs 和 UploadListProps.className；预览、下载、异步移除等有返回值的业务回调保留。原生根样式落 wrapper，详见[Upload API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/upload/index.zh-CN.md)。

### D-popconfirm-native-sessions

Popconfirm 的所属通知使用 Vue emits，确认 Promise 仍是业务回调；当前配置与 Token 由 Popconfirm 拥有，不误用 Popover 配置。异步结果只关闭发起它的已接受会话，卸载后不再触发旧关闭；引用暴露实际实例。详见[Popconfirm API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/popconfirm/index.zh-CN.md)。

### D-select-native-search-and-events

Select 的通知使用 Vue emits，value/open/searchValue 使用对应 v-model；showSearch 仅承载过滤与排序等搜索算法配置。原 showSearch.searchValue/onSearch/searchIcon 分别迁到顶层模型、search 事件与 #searchIcon，移除 onDropdownVisibleChange。当前配置、有效 Token、实际模板引用和共享引擎消费者同步修正；详见[Select API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/select/index.zh-CN.md)。AutoComplete 同步转发 searchValue 模型更新。

### D-drawer-native-lifecycle

Drawer 的 close/afterOpenChange/resize/resizeStart/resizeEnd 使用 Vue emits，引用暴露实际 nativeElement 与 focus。resizable 直接使用 boolean，原对象内回调迁为对应 Vue 事件（尺寸载荷为 number）；删除未消费的 panelRef/destroyInactivePanel。修复真实 motion 完成通知、延迟销毁、受控尺寸与拖拽、嵌套推移和焦点资源，详见[Drawer API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/drawer/index.zh-CN.md)。

### D-locale-provider-order

LocaleProvider 与 ConfigProvider 的静态确认语言来源按挂载顺序固定优先级，内容更新不重新占位；清空来源后旧清理不恢复过期语言。普通 Modal 只读取本应用响应式语言，静态 confirm 仍可显式传 locale；无上下文静态服务的全局来源边界保留。详见[Locale 当前契约](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/foundation/locale-contract.md)。

### D-a11y-accepted-navigation

useRovingFocus 的 activeIndex 按既有文档作为受控输入，拒绝请求不再修改已接受值或抢焦点，撤控保留已接受值。需要本地初值时不传受控 activeIndex，调用 setActive(index, false)；零偏移保持当前位置，跳末项使用 moveEnd。键盘事件保留原生阻止/输入法边界，挂载前播报在真实宿主就绪后保留。详见[a11y 当前契约](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/foundation/a11y-contract.md)。

### D-auto-complete-native-combobox

AutoComplete 的通知改为 Vue emits，并明确 value/searchValue/open 三个模型、实际模板引用与像素/条目滚动参数。backfill 只预览键盘候选，Enter/Tab/点击才提交；Tab 保留原生焦点移动。Provider 展示配置由真实包装者拥有，继续共享已文档化的 Select Token。原 showSearch.onSearch 迁为 search 事件，旧 onDropdownVisibleChange 迁 openChange；详见[AutoComplete API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/auto-complete/index.zh-CN.md)。

### D-color-picker-native-content

ColorPicker 的 panelRender/showText 内容函数直接迁为 #panelRender/#showText；panel 作用域改为稳定组件引用，可用 `<component :is="panel" />`，不再需要 VNode 渲染适配器。默认触发器和预设色块具备原生键盘交互，尺寸采用共享 SizeType，attrs 落到实际触发节点；PurePanel 使用正常文档流并转发真实槽/事件，移除轮询和高度镜像。当前配置、渐变 alpha 与数字颜色输入同步修正，详见[ColorPicker API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/color-picker/index.zh-CN.md)。

### D-transfer-native-models

Transfer 保留已有四槽成果，补齐 targetKeys/selectedKeys 双模型、所属 Vue 事件与真实引用。Search.handleClear 和 Operation.moveToLeft/moveToRight 命令 prop 改为 clear/move-to-left/move-to-right 事件；选择范围基于当前筛选视图，业务 key 和 Vue 节点身份保留。七 Token 接受 string/number 并读取当前主题；移除从未消费的 ListBodyProps.filteredItems，#list.filteredItems 保留。详见[Transfer API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/transfer/index.zh-CN.md)。

### D-picker-native-panels

Picker 面板引擎的通知使用 Vue emits，PickerPanel 提供 value/pickerValue/mode 三个模型；cellRender 内容 prop 迁为 #cellRender，对日期与时间列提供真实 Dayjs/number/meridiem 类型。当前时间配置、Provider、原生槽和面板引用直接消费；滚动对齐、取消与卸载资源已修复。DatePicker/RangePicker/Calendar 仅同步引擎消费桥，CellRenderInfo.locale 修正为实际面板语言子集，包装器其余契约继续各自整改。详见[Picker 当前契约](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/foundation/picker-contract.md)。

### D-dropdown-native-menu

Dropdown/DropdownButton 的开关、动效与主按钮通知使用 Vue emits，afterOpenChange prop 迁为 after-open-change 事件；真实引用保留既有三个 getter 方法。Provider、有效 Token、原生 attrs 与完整按钮/浮层槽真实消费，未实现的 icon 类型字段改用已有图标槽；id 落到实际触发节点。Menu 同步当前前缀、分组/动效、selectable 与键盘监听，语义样式传至实际菜单项。PurePanel 保持正常静态定位，详见[Dropdown API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/dropdown/index.zh-CN.md)。

### D-form-core-native-scopes

Form Core 的通知由 Vue emits 拥有，store/useForm 的业务回调仍保留。Form、Field、List 默认槽分别接收 `{ values, form }`、`{ control, meta, form }`、`{ fields, operations, meta }`，模板与 h() 使用同一对象；UI Form/FormItem 同步迁移，FormList 已有对象形态保留。外部 store、动态注册、受控 fields 和校验资源同步修正，实际宿主通过 nativeElement 返回。详见[Form Core 当前契约](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/foundation/form-core-contract.md)；UI Form 的完整外观整改仍单独推进。

### D-cascader-native-paths

Cascader/CascaderPanel 的通知使用 Vue emits，选择器提供 value/open/searchValue 三个模型。displayRender、optionRender、popupRender、showSearch.render、函数式标签与图标内容迁为原生槽；popupRender 的 menu 可直接用 `<component :is="menu" />`。移除未消费的 trigger/placeholder2 与重复开关通知，nativeElement 改为实际属性；过滤、排序和异步加载保留函数。修正类型安全的路径身份、当前配置/Token、键盘、异步会话和 raw 浮层传递，详见[Cascader API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/cascader/index.zh-CN.md)。

### D-date-picker-native-input-and-panels

DatePicker/RangePicker 的内容函数迁为 cellRender/panelRender/extraFooter/tagRender 等具名槽，移除无实际替换链路的 components/inputRender、失效的 changeOnBlur 与无运行时组件的 PurePanel 类型。通知使用 Vue emits，value/open/pickerValue/mode 支持模型请求；keydown 只接收原生 KeyboardEvent，preventDefault() 在内部操作前生效，暴露 DOM 引用准确包含 null。修正输入草稿/IME、受控撤控、范围活动端与禁用时间、只读面板键盘、动态槽与主题及观察器清理；TimePicker 仅同步关联包装桥，详见[DatePicker API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/date-picker/index.zh-CN.md)。

### D-menu-native-notifications

Menu 的选择/展开通知统一使用 Vue emits，原生键盘监听使用 onKeydown（模板为 @keydown），替代 React 拼法 onKeyDown；顶层 expandIcon 与静态子组件图标渲染迁为具名槽，数据项的图标和操作函数保留。移除从未消费的 children 类型，继续使用 items 数据源；实际 Overflow 根引用、当前 Provider/语义样式、已有十个 Token 和 popup/inline 层级职责同步修正，详见[Menu API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/menu/index.zh-CN.md)。

### D-tree-select-native-tree-owner

TreeSelect 的通知统一为 Vue emits，保留 value/open/searchValue/treeExpandedKeys/treeLoadedKeys 模型，监听 change 不再改变值的形态。顶层标题/标签/浮层与图标内容函数迁为具名槽，数据项 title/icon 与过滤、加载服务保留真实数据职责；旧开关通知别名改为 openChange，nativeElement() 改为实际属性。配置由 TreeSelect 自己拥有，继续共享 Tree/Select Token；修正原始数据服务载荷、异步 children 更新、键盘和实际 tree ARIA 目标，详见[TreeSelect API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/tree-select/index.zh-CN.md)。

### D-time-picker-native-owner

TimePicker/TimeRangePicker 固定为时间轴，移除从 DatePicker 误继承且无实际行为的 mode/defaultMode/update:mode、日期导航和多选标签声明，保留 value/open/pickerValue 模型与真实七/八个槽。两者读取当前 timePicker 配置并只合并一次语义样式，普通 Date Range 继续读取 rangePicker；独立 TimePicker 语言提示和动态撤回生效。没有新增 TimePicker Token 或内部面板，详见[TimePicker API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/time-picker/index.zh-CN.md)。

### D-test-utils-native-contracts

Test Utils 保留既有 Vue 测试入口，修正真实 VNodeChild、CSS/DOM 精确归一、焦点与原生属性断言、异常卸载/observer目标身份和收集器恢复；空执行范围不能冒称通过。ObserverBaseline.resizeTargets 由数量改为实际目标身份集合，包外没有旧字段消费者。C11 只检查公开组件的真实 runtime props，保留精确非模型数据豁免；Steps 同步补齐 update:current，模板可直接使用 v-model:current，原 change 数字载荷保留。

### D-checkbox-native-input-events

Checkbox 的 change 改为 `(event: Event, checked: boolean)`：首参为原生事件，第二参保留本次提议；移除合成 target/nativeEvent 包装及旧 Target DTO。其余 DOM 通知采用原生拼写与事件，Group change 保留值数组；值范围统一为实际支持的 string/number/boolean。修正父拒绝更新后的 checked/indeterminate、动态 skipGroup 注册、当前 Provider 和原生样式，引用暴露真实 nullable DOM。Radio 仅同步已证实的勾选恢复边界，完整事件迁移仍另行审计；Table/Transfer 已同步本次消费，详见[Checkbox API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/checkbox/index.zh-CN.md)。

### D-motion-native-slots-and-events

CSSMotion/MotionList 的可见性通知统一为 owned `visibleChanged` 事件，原 hooks.onVisibleChanged 迁为 `@visible-changed` / onVisibleChanged；其余有返回值的动效服务 hooks 保留。CSSMotion 将原生 attrs 与原 ref 合并到真实单个动画根，支持条件空槽和 Fragment，多个真实根明确不支持；MotionList 默认槽泛型保留移除项的浅快照元数据，component 支持原生标签、Vue 组件或 null。修正动态配置、异步准备错误归属与根替换后的监听释放，Trigger、Modal、Segmented、Form 和 Masonry 同步必要消费。详见[Motion 当前契约](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/foundation/motion-contract.md)。

### D-form-native-content-and-instances

Form 的 requiredMark 内容函数迁为 `#requiredMark={ label, required }`，label 是可直接渲染的稳定组件；feedbackIcons / hasFeedback.icons 迁为 Form 或 FormItem 的 `#feedbackIcon={ status, errors, warnings }`，hasFeedback 保留 boolean。useFormInstance 读取最近的真实 Form 实例，useForm 保留工厂职责；getFieldInstance 返回实际控制实例，是否支持 focus 取决于该控件。移除无消费的 Item status/fieldId，使用已有 validateStatus/id；requiredMark 在 Form 上配置。同步修正动态槽撤除、路径聚合、原生 attrs、实际焦点/滚动、响应式列与当前十一 Token，详见[Form API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/form/index.zh-CN.md)。

### D-table-native-data-and-content

Table 的顶层 title/footer/summary/expandedRowRender/expandIcon/emptyText 内容函数迁为具名槽，expandable 内同名全表内容函数也统一迁移；共享语言与组件 locale.emptyText 只承载静态内容，动态空态使用 #emptyText。按列或数据承担业务职责的 render/title/filterDropdown、排序过滤和选择操作函数保留。通知使用 Vue emits，change 保留四个实际业务载荷，scroll 使用原生 Event；公开泛型贯穿数据、列、槽、事件与真实模板引用，不要求用户添加索引签名。修正受控提议与撤控、同 key 行内容与焦点、当前配置和实际滚动资源；虚拟列表的 Vue holder/行按真实 HTMLElement 根测量，隐藏测量单元不再重复挂载表头交互，不可展开行使用装饰占位。详见[Table API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/table/index.zh-CN.md)。

### D-radio-native-input-and-group

Radio/RadioButton 的 change 改为 `(event: Event, checked: boolean)`，RadioGroup 的 change 改为 `(value: RadioValue, event: Event)`，分别保留 checked/value 模型；RadioChangeEvent 仅为原生 Event 别名，不再构造 target/nativeEvent 包装。选项 change 同步原生双参，Table 保留同一事件，Calendar/Header Demo 使用已有 update:value。移除无实际职责的 Radio skipGroup/type/optionType 声明，Group 的 optionType 保留。修正当前 Provider/十六 Token、完整内容和原生 attrs、选项身份/焦点、Button 引用与单次通知；已交付的受控整组 DOM 恢复继续保留，详见[Radio API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/radio/index.zh-CN.md)。

### D-segmented-native-selection

Segmented 的 change/keydown 由 Vue emits 拥有，value 模型保持；原生 attrs/style 落真实根，选项 id 与表单 value 真实消费。label/icon 使用完整 VNodeChild，语义样式使用 CSSProperties 与当前 SegmentedProps，尺寸接共享 SizeType（含 medium）。选中或首个可用 radio 是唯一 Tab 入口，拒绝提议后恢复已接受的勾选与焦点，RTL/IME/取消默认行为同步修正。当前八 Token 和快速反向 thumb 动效读取有效配置并清理失效资源；原 DOM 参考保留，详见[Segmented API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/segmented/index.zh-CN.md)。

### D-calendar-native-content-and-panels

Calendar 的 headerRender/cellRender/fullCellRender 内容 prop 及四个旧别名统一迁为已有同名具名槽，作用域使用具名对象；移除对应纯回调类型，保留 Header 作用域中的 onChange/onTypeChange 操作服务。value/mode 模型与 change/panelChange/select 顺序保持，Header 使用 RadioGroup 的 update:value。修正条件槽、原生 attrs/真实引用、当前配置/语言/六 Token，并将当前方向传给实际 Picker 面板；复用已交付的面板算法，详见[Calendar API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/calendar/index.zh-CN.md)。

### D-watermark-native-drawing-lifecycle

Watermark 的 remove 通知改由 Vue emits 拥有，模板使用 @remove，h() 的 onRemove 仍是自然监听器。fontSize 保留 number/string，由浏览器解析合法 CSS 单位；移除无效的 fontStyle="none"。修正实际图片身份缓存、异步图片竞态、当前原生 attrs/样式、继承面板和观察器/帧的释放；保留既有水印几何及防篡改行为，真实 Modal 消费同步验证，详见[Watermark API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/watermark/index.zh-CN.md)。

### D-card-native-content-and-tabs

Card 的 tabChange/update:activeTabKey 由 Vue emits 拥有，支持 v-model:activeTabKey；h() 的 onTabChange 仍是自然监听器。Tabs 保留选择状态职责，tabProps 不再建立第二个受控来源。已有 actions 内容增加 #actions 入口；Meta 的默认槽作为 description 的后备，具名 description 槽（含空槽）优先，其次是显式 description 数据。修正条件内容身份与焦点、Card/Grid/Meta 原生 attrs/真实引用、当前配置和十三 Token，详见[Card API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/card/index.zh-CN.md)。

### D-splitter-native-panels-and-resize

Splitter 的 resizeStart/resize/resizeEnd/collapse/draggerDoubleClick 统一由 Vue emits 拥有，移除重复回调 prop 通道，模板仍使用自然的 @resize-start 等写法。Panel 保留真实 Vue 节点、原生 attrs/StyleValue、默认槽和可访问的 nativeElement，尺寸与折叠状态按 key 归属；受控拒绝不写入本地状态，撤控保留已接受值，布局顺序变化取消旧拖拽。补齐分隔条键盘和当前四个有效 Token，保留既有尺寸算法，详见[Splitter API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/splitter/index.zh-CN.md)。

### D-modal-native-content-and-sessions

普通 Modal 的 ok/cancel/afterClose/afterOpenChange 改由 Vue emits 拥有，取消/关闭支持 open 模型请求，OK 保留业务通知职责。modalRender/footer 内容函数迁为 #modalRender={ModalPanel}、#footer={OkBtn,CancelBtn}，提供稳定可直接使用的组件；命令式确认的异步操作与程序内容配置保留。useModal 仍返回 [api,holderVNode]，结果以 ModalHookInstance 准确描述 PromiseLike<boolean>，修正早期调用、会话结算/注销、关闭后更新及当前 confirmLoading。删除从未生效的普通 focusTrap 和命令式 open 声明，分别使用 focusable.trap、destroy()；补齐实际 Portal 容器、当前配置/六 Token、原生 attrs、焦点与资源，详见[Modal API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/modal/index.zh-CN.md)。

### D-slider-native-handles-and-proposals

Slider 的 handle/activeHandle 槽准确公开实际 nodeProps/ref/事件及当前 index/value，ColorPicker 使用同一类型。value 支持已有 null 输入，通知仍返回 number/number[]；beforeChange 统一为有效交互的首个提议，changeComplete 使用该会话最后提议，拒绝更新不改变已接受状态，无变更或取消不伪报完成。原生 tabindex/ARIA 落实际把手，键盘取消、拖拽/触摸及卸载资源、当前十八 Token 和范围 Tooltip 同步修正；删除 Tooltip 未消费的开关回调及内部 value/draggingDelete 声明，已有 open/formatter 保留，详见[Slider API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/slider/index.zh-CN.md)。

### D-carousel-native-slides-and-config

Carousel 的 beforeChange/afterChange/swipe/edge 使用所属 Vue emits，模板自然支持短横线事件名；原生 style/attrs 落真实根，内层样式用 styles.slider，移除未消费的 easing。箭头槽提供既有原生按钮的完整内容，原件 key/ref 与条件槽保持真实 Vue 归属；克隆按实际可见范围提供交互，原生 ID 关联和透传插槽 ref 在克隆边界处理。修正动态配置、自动播放暂停原因、动画/尺寸资源及当前八 Token；克隆仍是独立组件实例，不镜像任意内部状态，详见[Carousel API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/carousel/index.zh-CN.md)。

### D-tour-native-target-and-popup

Tour 保留 open/current 模型与已有具名槽，拒绝请求不泄漏到撤控状态，异步步骤和真正重开分别处理。actions 的 originNode 改为稳定可直接渲染的组件；popupAlign 使用 Vue emits，步骤按钮传原生 MouseEvent 并支持取消导航。原生 attrs 经私有 Trigger 通道落真实弹层，修正当前目标/容器、配置/语言/Token、PurePanel 及焦点；遮罩使用原生 SVG 属性，实际滚动、换容器与切换遮罩保持正确几何和子树身份。没有新增观察任意纯位置重排的能力，详见[Tour API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/tour/index.zh-CN.md)。

### D-affix-anchor-native-scroll-and-links

Anchor 与 Anchor.Link 的 click 使用所属 Vue emits，载荷为原生 MouseEvent 和链接信息，preventDefault() 可取消内部导航；change 保留原始 href。Anchor 默认槽是正式组合入口，Anchor.Link 的标题使用 #title 或 title，子链接使用默认槽，移除未消费的 children prop。原生链接交互落实际 a 元素，换容器、当前配置、指示条和卸载资源按真实节点维护；Affix 保留 updatePosition 与既有几何判据，显式未就绪目标会释放旧监听，固定内容尺寸变化同步占位。详见[Anchor API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/anchor/index.zh-CN.md)和[Affix API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/affix/index.zh-CN.md)。

### D-listy-native-generics-and-content

Listy 使用真实泛型 Vue 组件，保留任意数据类型与有效字符串/数字 key，rowKey 字段按其实际值类型约束。itemRender 迁为 #default={item,index}，group.title 迁为 #groupHeader={groupKey,items,sticky,fixed}，group.key 保留数据分组职责；类型贯穿模板、h()、插槽与 scrollTo 引用。toTaggedKey 的结果包含 key 的原始类型，数字和字符串不再碰撞；不要自行拼接旧格式。修正 Raw/Virtual 的真实滚动目标、跨分组节点身份、组头定位与资源释放，Provider 和当前两个 Token 实际消费，详见[Listy API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/listy/index.zh-CN.md)。

### D-notices-native-sessions-and-panels

Message/Notification 保留命令式 API、有效服务回调和零参数 holder 工厂，提前调用进入实际挂载队列；Message 句柄在真正终止时结算，同 key 的各次等待均有效，手动关闭、销毁、淘汰和卸载不新增 public onClose 通知。关闭按钮和计时关闭仍调用当前 onClose；原始数字/字符串 key 分离，更新重置当前计时。单条配置中移除未消费的 classNames/styles.list 与 listContent，列表语义继续在 hook/全局配置中设置；PurePanel/PureList 使用准确类型、原生槽与事件。补齐当前十个 Token、Provider/关闭图标类型与真实容器消费，Modal/Tag 的共享关闭图标链同步验证，详见[Message API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/message/index.zh-CN.md)和[Notification API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/notification/index.zh-CN.md)。

### D-app-native-services-and-host

AppConfig 和 useApp() 改用真实通知配置及 MessageInstance、NotificationInstance、ModalHookAPI，静态 App.useApp 保留相同准确类型。useApp() 必须在真实 App 提供的 Vue 注入上下文中调用，缺少 Provider 时明确报错，不再返回伪造的空 API。保留原有四种宿主标签与 component=false、默认槽、嵌套配置和实例隔离；当前 Provider 根样式与原生 attrs 合并到实际宿主，动态切换宿主保留服务内容和生命周期。详见[App API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/app/index.zh-CN.md)。

### D-utils-native-refs-and-resources

RefLike 删除没有真实消费者的 React `{current}` 包装，使用 Vue 可写 value 引用或函数 ref；组件自己的 current 业务 prop 继续按实例处理。useComposeRef 接收一个数组、Ref 或 getter 集合源，例如 `useComposeRef(() => [localRef, callback])`；getNodeRef 返回真实 public expose 或 DOM，不再允许任意指定结果泛型。状态工具保留 T 与嵌套 Ref 的身份，既有受控提议和撤控算法保持；mergeProps 类型描述实际的后值覆盖，输入限对象、null、undefined，共享关闭配置同步规范化。补齐所属文档、独立订阅释放、取消、临时 CSS 容器及合法颜色输入边界，详见[Utils 当前契约](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/foundation/rc-util-contract.md)。开发阶段直接迁移，无兼容分支或弃用期；声明产物与全库验收留到统一冻结阶段。

### D-position-owner-document-and-clipping

Position 的公开签名及纯几何算法保持，测量使用目标所属文档、组合祖先和当前逐轴裁剪，修正边框盒缩放、overflow-clip-margin 与临时样式恢复。共享 Trigger 将视口和滚动区域分别传入对齐引擎，按当前容器绑定滚动及所属窗口 resize；迁移已有弹层不重建业务子树，关闭和卸载释放监听。仅支持同一 Document 内的轴对齐矩形，不新增跨 iframe 坐标换算或轮廓裁剪能力，详见[Position 当前契约](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/foundation/position-contract.md)。

### D-border-beam-native-host-and-effect

BorderBeam 的原生 class/style/事件合并到默认槽的单一 HTML 宿主；旧组件 className 改用 classNames.effect，旧装饰 style 改用 styles.effect。Provider 的装饰配置保留原义。完整 Vue 内容、模板 ref、key 与组件插槽保留各自归属，条件或异步根更新后跟随真实宿主；多根、文本及 SVG 内容完整透传但不产生描边。动态 textContent 移除装饰节点时只重建描边，动画会重启，业务内容与焦点保持；共享采样跟随宿主所属文档并在卸载释放，详见[BorderBeam API](https://github.com/apollocmh/apollo-design-ui/blob/master/packages/ui/src/border-beam/index.zh-CN.md)。开发阶段直接迁移，无旧形态兼容层。

### D-virtual-list-native-generics-and-holder

VirtualList/Filler 使用真实泛型 Vue 组件与所属 emits，沿用 default={item,index,style,offsetX} 和 extra 槽；旧多参数 RenderFunc/RenderProps 类型、无效 showScrollBar 与无消费者的 lastDiff 诊断引用直接移除。公开引用保留只读 nativeElement/containerElement、getScrollInfo、scrollTo；按业务 key 读取高度缓存使用 get，数字与同文字符串 key 分离。id/role/ARIA/tabindex 和键盘、焦点监听落真实滚动 holder，class/style/data 留 outer，innerProps 独立指向内容层。Table、Listy、Select、Tree 同步使用实际泛型、作用域与 holder 引用，修正高度/宽度、RTL 和异步滚动请求生命周期，详见[VirtualList 当前契约](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/foundation/virtual-list-contract.md)。开发阶段直接迁移，无旧回调或 DOM 形态兼容层。



---

# 图标

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/guide/icons

图标来自独立包 `@apollo-design/icons`，与 `@apollo-design/ui` 分开安装与按需引入。它提供 **848 个** 图标：447 个 Outlined、251 个 Filled、150 个 TwoTone；完整目录见 [图标资源页](https://apollocmh.github.io/apollo-design-ui/components/icon)。

### 安装与引入

```bash
pnpm add @apollo-design/icons
```

```vue
<script setup lang="ts">
import { SearchOutlined } from '@apollo-design/icons';
</script>

<template>
  <SearchOutlined />
</template>
```

图标是普通 Vue 组件，颜色继承 `currentColor`，尺寸继承 `font-size`；也可以直接用 `style` / `class` 覆盖：

```vue
<template>
  <SearchOutlined style="font-size: 24px; color: #1677ff" />
  <SearchOutlined :rotate="90" />
  <SearchOutlined spin />
</template>
```

### TwoTone 调色

TwoTone 图标支持 `twoToneColor`（单个图标）或 `setTwoToneColor`（全局）：

```ts
import { setTwoToneColor } from '@apollo-design/icons';

setTwoToneColor('#1677ff');
```

### IconProvider

`IconProvider` 用来覆盖图标类名前缀，默认是 `apollo-icon`：

```vue
<template>
  <IconProvider :value="{ prefixCls: 'my-icon' }">
    <SearchOutlined />
  </IconProvider>
</template>
```

### 自定义图标

```ts
import { createIcon } from '@apollo-design/icons';

export const MyIcon = createIcon(
  {
    name: 'my-icon',
    theme: 'outlined',
    icon: {
      tag: 'svg',
      attrs: { viewBox: '0 0 24 24' },
      children: [{ tag: 'path', attrs: { d: 'M12 2 L22 22 L2 22 Z' } }],
    },
  },
  'MyIcon',
);
```

从 iconfont.cn 接入：

```ts
import { createFromIconfontCN } from '@apollo-design/icons';

const IconFont = createFromIconfontCN({
  scriptUrl: '//at.alicdn.com/t/c/font_xxx.js',
});
```

### 无障碍

图标默认通过 `role="img"` 语义输出。装饰性图标请加 `aria-hidden="true"`；承载语义的图标请提供 `aria-label`（或 `ariaLabel` prop），不要让读屏器去猜。



---

# Affix

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/affix


# Affix 固钉

滚动到指定偏移后，将内容固定到窗口或实际滚动容器的可视边缘。默认插槽承载完整 Vue 内容。

```vue
<Affix :offset-top="16" :target="() => scrollArea" @change="onAffixed">
  <button>固定工具栏</button>
</Affix>
```

## API

| Prop | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| offsetTop | 顶部固钉偏移 | number | 两种偏移都未传时为 0 |
| offsetBottom | 底部固钉偏移；两个条件同时命中时顶部优先，顶部未命中时仍可命中底部 | number | — |
| target | 返回实际滚动元素或 Window；未传依次使用 Provider.getTargetContainer、window | () => HTMLElement \| Window \| null \| undefined | — |
| prefixCls | 当前组件类名前缀 | string | apollo-affix |

`target` 返回 null/undefined 表示尚未就绪，释放旧目标监听并撤除固钉状态，不退回 window。响应式 ref 就绪或替换后自动同步；非响应式目标变化可调用已有 `updatePosition()` 重新读取。

| 事件 | 载荷 | 时机 |
| --- | --- | --- |
| change | affixed: boolean | 实际固钉状态翻转时；同一状态的滚动不重复通知 |

| 插槽 | 说明 |
| --- | --- |
| default | 固钉内容，保留完整 VNodeChild 和节点身份 |

| AffixRef | 说明 |
| --- | --- |
| updatePosition(): void | 合并到下一帧重新测量当前目标和内容 |

没有新增实例方法。模板 ref 可声明为 `ref<AffixRef | null>(null)`。

## 原生属性与当前配置

根是外层占位测量 div，原生 class/style、id、data、ARIA 和监听器只落此处。class/style 使用 Vue 的字符串、数组和对象合并，调用者样式覆盖 `ConfigProvider.components.affix.style`；这些字段不另声明成组件 Props。固钉层与占位层是内部定位节点。

`getPrefixCls`、组件配置和主题读取当前 Provider。唯一组件 Token 是 `zIndexPopup`，默认由 `zIndexBase + 10` 派生；替换、撤除和显式 0 均作用于实际固钉层。

```vue
<ConfigProvider :theme="{ components: { Affix: { zIndexPopup: 20 } } }">
  <Affix :offset-top="0">工具栏</Affix>
</ConfigProvider>
```

## 几何与资源

保留顶部/底部的亚像素比较与外层布局测量基准。顶部条件优先于底部条件，并非删除另一个条件。固定宽度跟随外层可用宽度；内容保留自然高度，其真实尺寸通过已有 ResizeObserver 同步占位，支持增长和缩小，不重挂内部输入。

只在挂载后测量和绑定。监听当前目标、影响目标或占位层位置的滚动祖先及目标所属窗口的滚动；外页或嵌套祖先滚动移动目标后，顶部和底部固钉都按当前位置更新。滚动事件保持逐帧合并与同位置快路径；内容/容器的尺寸通知走完整测量。换目标、目标变为空和卸载释放这些监听、观察及待执行帧，SSR 不调度这些副作用。没有为无尺寸/滚动/显式更新信号的任意位置重排增加观察或轮询。

## Demo

basic、offset-bottom、on-change、target、update-position；原有几何与 s54 监听幂等回归保留。统一九维与发布验收另行执行。


## 基础 (basic)

最简单的用法：滚动到 `offsetTop` 之后，按钮固钉在顶部。

固钉时组件会渲染一个**等高占位层**（`aria-hidden`），避免页面布局跳动；
且**只有此时**内层才有 `apollo-affix` 类名（`position: fixed`）。

### basic.vue

```vue
<script setup lang="ts">
import { Affix, Button } from '@apollo-design/ui';
</script>

<template>
  <div style="min-height: 760px; padding-top: 120px">
  <Affix :offset-top="80">
    <Button type="primary">固定在顶部 80px</Button>
  </Affix>
    <p style="margin-top: 24px">Scroll this preview to observe the fixed position.</p>
  </div>
</template>
```

## 固定在底部 (offset-bottom)

`offsetBottom` 与 `offsetTop` **互斥**：两者都传时只有 `offsetTop` 生效
（antd 的 `internalOffsetTop` 互锁推导，见 `docs/analysis/affix.md` §3）。

### offset-bottom.vue

```vue
<script setup lang="ts">
import { Affix, Button } from '@apollo-design/ui';
</script>

<template>
  <div style="min-height: 760px; padding-top: 420px">
  <Affix :offset-bottom="80">
    <Button>固定在底部 80px</Button>
  </Affix>
    <p style="margin-top: 24px">Scroll this preview to observe the fixed position.</p>
  </div>
</template>
```

## 固钉状态改变回调 (on-change)

`@change` 只在状态**翻转**时触发（连续固钉不会重复发）。
Vue 侧是 `emit('change', affixed)`，模板上写 `@change` —— antd 的 `onChange` prop 不移植成 prop（规则 C19）。

### on-change.vue

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Affix, Button } from '@apollo-design/ui';

const affixed = ref(false);
</script>

<template>
  <div style="min-height: 760px; padding-top: 120px">
  <Affix :offset-top="120" @change="(v) => (affixed = v)">
    <Button>{{ affixed ? '已固钉' : '未固钉' }}</Button>
  </Affix>
    <p style="margin-top: 24px">Scroll this preview to observe the fixed position.</p>
  </div>
</template>
```

## 滚动容器 (target)

`target` 是一个**返回元素或 `window` 的函数**（不是元素本身）。
换绑 `target` 时，旧 target 上的监听也会被解绑。

⚠️ 固定在容器底部时，偏移量是「容器可视区底边到**视口**底边的距离」参与计算
（`getFixedBottom` 用 `window.innerHeight`，不是容器高度）。

### target.vue

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Affix, Button } from '@apollo-design/ui';

const container = ref<HTMLElement | null>(null);
const getTarget = () => container.value;
</script>

<template>
  <div ref="container" style="height: 300px; overflow: auto; border: 1px solid var(--apollo-color-border); border-radius: var(--apollo-border-radius)" tabindex="0" aria-label="Affix scroll container">
    <div style="height: 640px; padding: 80px 12px 12px">
    <Affix :target="getTarget" :offset-top="10">
      <Button>固定在容器顶部</Button>
    </Affix>
    <p>Scroll this container to pin the button at its top edge.</p>
    </div>
  </div>
</template>
```

## 手动更新位置 (update-position)

`ref` 只暴露 `updatePosition`（与 antd 的 `useImperativeHandle` 一致）：
内容尺寸或布局在程序里变化后，手动触发一次重新测量。

尺寸变化通常由内部的 `ResizeObserver` 自动捕捉，无需手动调用。

### update-position.vue

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Affix, type AffixRef, Button } from '@apollo-design/ui';

const affixRef = ref<AffixRef | null>(null);
</script>

<template>
  <div style="min-height: 760px; padding-top: 120px">
  <Affix ref="affixRef" :offset-top="60">
    <Button @click="affixRef?.updatePosition()">手动重新测量</Button>
  </Affix>
    <p style="margin-top: 24px">Scroll this preview to observe the fixed position.</p>
  </div>
</template>
```

---

# Alert

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/alert


在页面中展示需要关注的信息；支持完整 Vue 内容插槽和原生关闭按钮。全部15个实际示例见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/alert/demo)。

## Props

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| type | 提示类型 | `'success' \| 'info' \| 'warning' \| 'error'` | banner 时 warning，否则 info |
| variant | 显式值优先于当前 `components.alert.variant` | `'outlined' \| 'filled'` | outlined |
| title | 标题文本；富内容走 #title | `string` | — |
| message | 废弃标题别名，title 未传时使用 | `string` | — |
| description | 描述文本；富内容走 #description | `string` | — |
| showIcon | 是否显示图标；显式 false 抑制 banner 默认图标 | `boolean` | banner 时 true，否则 false |
| banner | 顶部通告形态 | `boolean` | false |
| closable | boolean 或关闭配置；对象恒可关，当前 Provider 可给默认值 | `boolean \| AlertClosable` | false |
| closeIcon | 遗留标量图标，推荐 #closeIcon 或 closable.closeIcon | `string \| number \| boolean \| null` | — |
| closeText | 废弃关闭文案，推荐 #closeIcon | `string` | — |
| afterClose | 遗留完成回调，推荐 @after-close | `() => void` | — |
| prefixCls | DOM 类名前缀；自定义前缀需预载对应静态 CSS | `string` | apollo-alert |
| id / role | 实际根 div 的属性 | `string` | role=alert |
| classNames / styles | root/icon/section/title/description/actions/close；对象或读取当前合并 props 的函数 | `AlertSemanticValue<…>` | — |

`class`、`style`、tabindex、ARIA/data、普通原生监听器和 once 等修饰符落在实际根 div；`nativeElement` 指向该节点。`title` 已是内容 prop，不另作同名原生提示属性。原生根事件使用 DOM Event；onClick/onMouseenter/onMouseleave 为对应监听器写法。

语义函数的 `props` 包括当前解析后的 type、variant、prefixCls、role、图标显示和关闭开关；role 默认 alert，显式值优先。

Provider 四类图标的 null/undefined 沿用默认图标回退，默认图标按装饰内容处理；自定义图标语义由内容负责。

## Slots

| 插槽 | 说明 |
| --- | --- |
| #title | 完整标题内容，存在则覆盖 title/message，包括有意为空。 |
| #description | 完整描述；空内容不回退，且不保留 with-description 布局。 |
| #icon | 完整类型图标内容；空槽抑制默认图标，showIcon=false 仍优先。 |
| #action | 完整操作内容，支持多个原生操作节点。 |
| #closeIcon | 关闭按钮内的文本/图标；存在则覆盖所有图标配置，空槽不回退。 |

五个槽均在当前 render 读取，支持条件添加/移除、Fragment 与0。没有 default→title 的隐式通道。关闭内容优先级为 #closeIcon、closable.closeIcon、closeText、遗留 closeIcon、Provider对象图标、Provider closeIcon、默认图标；配置值按是否提供判定，0/false/null/空串不被默认图标覆盖。

## Events 与关闭状态

| 事件 | 载荷与时机 |
| --- | --- |
| close | 实际关闭按钮 click 的 MouseEvent，包含原生 Enter/Space 激活；每实例接受一次关闭请求。 |
| after-close | 内部关闭完成并移除后通知一次；禁动效和减少动画也完成。 |

onClose/onAfterClose 是事件监听器的程序化写法。`closable.onClose/afterClose` 保留业务配置能力，不能抑制 Vue 事件；同一函数同时作为配置与监听器时不重复调用。配置 afterClose 优先于遗留 plain afterClose。关闭按钮默认可访问名称为 Close，可用 closable 的 aria-label/aria-labelledby 定义业务名称；其 aria/data 落在关闭按钮，根 ARIA 仍属根。

关闭是内部一次性状态，没有 open/visible/v-model 或取消钩子。父级通过 v-if/key 控制挂载和重新显示；更改 closable 不重新打开已关闭实例。父级在 @close 中直接卸载时，不会冒充内部关闭完成事件。保留遗留 closeText 真值触发可关闭的既有优先级；显式 closable boolean 决定通常关闭开关。

## Ref

`AlertRef.nativeElement: HTMLDivElement | null`，关闭完成或卸载后为 null。

## ErrorBoundary

`Alert.ErrorBoundary` 与 `AlertErrorBoundary` 为同一有类型的组件。完整默认 slot 是健康内容，不额外包装 DOM；无 v-model、reset 方法或公开 expose。通过父级 key 重挂可恢复。

| 参数 | 说明 | 类型 |
| --- | --- | --- |
| title / message | 错误标题数据，缺省使用 String(error)；message 为旧别名 | `VNodeChild` |
| description | 错误描述数据，缺省以 pre 展示 Vue 错误阶段信息 | `VNodeChild` |
| id | 错误回退 Alert 的 id | `string` |

Vue onErrorCaptured 捕获实际后代的 setup/渲染/生命周期及所属事件错误并阻断上抛，包括抛出0/false/null/undefined。边界自身或脱离 Vue 调用链的错误不属于此边界。class/style/ARIA/native attrs 的原生落点是错误回退 Alert，健康 Fragment 不分配这些 attrs 到任意业务子节点。

默认错误详情为名为 Error details 的可聚焦 region；窄视口下支持原生键盘横向滚动。提供自定义 description 数据时，其交互与语义由该内容负责。

## Theme

| Token | 作用 | 默认来源 |
| --- | --- | --- |
| borderRadius | 圆角 | borderRadiusLG |
| withDescriptionIconSize | 带描述图标尺寸 | fontSizeHeading3 |
| defaultPadding | 普通内边距 | paddingContentVerticalSM + 横向12px |
| withDescriptionPadding | 描述内边距 | paddingMD / paddingContentHorizontalLG |

最近 `theme.components.Alert` 的四字段与当前 Alias 实时消费，移除覆盖恢复当前主题。原生根 `--apollo-alert-*` 变量优先，默认/暗色/紧凑/组合保持作用域；关闭遵循 theme.token.motion 和 prefers-reduced-motion。

显式空 ThemeProvider 仍是最近的主题来源，恢复默认 Alias 和四个 Token；其下未配置主题的 ConfigProvider 延续该来源。没有主题来源的 ConfigProvider 不写组件主题变量，页面 CSS 的暗色/紧凑作用域继续生效。

迁移与验证范围见 `docs/migrations/alert-contracts.md`、`docs/audit/2026-10-29-alert-contract-audit.md`。


## 基本 (basic)

最简单的用法，适用于简短的警告提示。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { Alert } from '@apollo-design/ui';
</script>

<template>
  <Alert title="Success Text" type="success" />
</template>
```

## 四种样式 (description)

共有四种样式 `success`、`info`、`warning`、`error`。

### description.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 description demo
import { Alert } from '@apollo-design/ui';
</script>

<template>
  <div>
    <Alert
      title="Success Text"
      description="Success Description Success Description Success Description"
      type="success"
    />
    <br />
    <Alert
      title="Info Text"
      description="Info Description Info Description Info Description Info Description"
      type="info"
    />
    <br />
    <Alert
      title="Warning Text"
      description="Warning Description Warning Description Warning Description Warning Description"
      type="warning"
    />
    <br />
    <Alert
      title="Error Text"
      description="Error Description Error Description Error Description Error Description"
      type="error"
    />
  </div>
</template>
```

## 可关闭的警告提示 (closable)

显示关闭按钮，点击可关闭警告提示。`@close` 接收真实的原生 `MouseEvent`；关闭完成使用 `@after-close`。

### closable.vue

```vue
<script setup lang="ts">
import { Alert } from '@apollo-design/ui';

const onClose = (e: MouseEvent) => {
  console.log(e, 'I was closed.');
};
</script>

<template>
  <div>
    <Alert
      title="Warning Title"
      type="warning"
      :closable="{ closeIcon: true, 'aria-label': 'close' }"
      @close="onClose"
    />
    <br />
    <Alert
      title="Success Title"
      type="success"
      :closable="{ closeIcon: true, 'aria-label': 'close' }"
      @close="onClose"
    />
    <br />
    <Alert
      title="Info Title"
      type="info"
      :closable="{ closeIcon: true, 'aria-label': 'close' }"
      @close="onClose"
    />
    <br />
    <Alert
      title="Error Title"
      type="error"
      :closable="{ closeIcon: true, 'aria-label': 'close' }"
      @close="onClose"
    />
  </div>
</template>
```

## 顶部公告 (banner)

页面顶部通告形式，默认有图标且 `type` 为 'warning'。

### banner.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 banner demo
import { Alert } from '@apollo-design/ui';
</script>

<template>
  <div>
    <Alert title="Warning text" banner />
    <br />
    <Alert
      title="Very long warning text warning text text text text text text text"
      banner
      closable
    />
    <br />
    <Alert :show-icon="false" title="Warning text without icon" banner />
    <br />
    <Alert type="error" title="Error text" banner />
  </div>
</template>
```

## 可关闭的警告提示 (icon)

可口的图标让信息类型更加醒目。

### icon.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 icon demo
import { Alert } from '@apollo-design/ui';
</script>

<template>
  <div>
    <Alert title="Success Tips" type="success" show-icon />
    <br />
    <Alert title="Informational Notes" type="info" show-icon />
    <br />
    <Alert title="Warning" type="warning" show-icon closable />
    <br />
    <Alert title="Error" type="error" show-icon />
    <br />
    <Alert
      title="Success Tips"
      description="Detailed description and advice about successful copywriting."
      type="success"
      show-icon
    />
    <br />
    <Alert
      title="Informational Notes"
      description="Additional description and information about copywriting."
      type="info"
      show-icon
    />
    <br />
    <Alert
      title="Warning"
      description="This is a warning notice about copywriting."
      type="warning"
      show-icon
      closable
    />
    <br />
    <Alert
      title="Error"
      description="This is an error message about copywriting."
      type="error"
      show-icon
    />
  </div>
</template>
```

## 自定义图标 (custom-icon)

可口的图标让信息类型更加醒目。

### custom-icon.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 custom-icon demo
import { SmileOutlined } from '@apollo-design/icons';
import { Alert } from '@apollo-design/ui';
</script>

<template>
  <div>
    <Alert title="showIcon = false" type="success">
      <template #icon><SmileOutlined /></template>
    </Alert>
    <br />
    <Alert title="Success Tips" type="success" show-icon>
      <template #icon><SmileOutlined /></template>
    </Alert>
    <br />
    <Alert title="Informational Notes" type="info" show-icon>
      <template #icon><SmileOutlined /></template>
    </Alert>
    <br />
    <Alert title="Warning" type="warning" show-icon>
      <template #icon><SmileOutlined /></template>
    </Alert>
    <br />
    <Alert title="Error" type="error" show-icon>
      <template #icon><SmileOutlined /></template>
    </Alert>
    <br />
    <Alert
      title="Success Tips"
      description="Detailed description and advice about successful copywriting."
      type="success"
      show-icon
    >
      <template #icon><SmileOutlined /></template>
    </Alert>
    <br />
    <Alert
      title="Informational Notes"
      description="Additional description and information about copywriting."
      type="info"
      show-icon
    >
      <template #icon><SmileOutlined /></template>
    </Alert>
    <br />
    <Alert
      title="Warning"
      description="This is a warning notice about copywriting."
      type="warning"
      show-icon
    >
      <template #icon><SmileOutlined /></template>
    </Alert>
    <br />
    <Alert
      title="Error"
      description="This is an error message about copywriting."
      type="error"
      show-icon
    >
      <template #icon><SmileOutlined /></template>
    </Alert>
  </div>
</template>
```

## 自定义操作项 (action)

可以在右上角自定义操作项。

### action.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 action demo
import { Alert, Button } from '@apollo-design/ui';
</script>

<template>
  <div>
    <Alert
      title="Success Tips"
      type="success"
      show-icon
      closable
    >
      <template #action>
        <Button size="small" type="text">UNDO</Button>
      </template>
    </Alert>
    <br />
    <Alert
      title="Error Text"
      show-icon
      description="Error Description Error Description Error Description Error Description"
      type="error"
    >
      <template #action>
        <Button size="small" danger>Detail</Button>
      </template>
    </Alert>
    <br />
    <Alert title="Warning Text" type="warning" closable>
      <template #action>
        <Button type="text" size="small">Done</Button>
      </template>
    </Alert>
    <br />
    <Alert
      title="Info Text"
      description="Info Description Info Description Info Description Info Description"
      type="info"
      closable
    >
      <template #action>
        <div class="demo-alert-action-col">
          <Button size="small" type="primary" block>Accept</Button>
          <Button size="small" danger ghost block>Decline</Button>
        </div>
      </template>
    </Alert>
  </div>
</template>

<style scoped>
.demo-alert-action-col {
  display: flex;
  flex-direction: column;
  gap: 8px;
  min-width: 80px;
}
</style>
```

## 填充态 (filled)

通过 `variant="filled"` 隐藏边框。

### filled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 filled demo
import { Alert } from '@apollo-design/ui';
</script>

<template>
  <Alert title="Info Text" type="info" variant="filled" />
</template>
```

## 平滑地卸载 (smooth-closed)

`@close` 通知原生关闭请求，`@after-close` 在内部关闭完成后通知父级。减少动画偏好或 `theme.token.motion=false` 时也会完成移除并发出一次完成事件。Alert 没有受控 open/visible 模型；通过父级 `v-if` 重新挂载可再次显示。

### smooth-closed.vue

```vue
<script setup lang="ts">
import { Alert, Button } from '@apollo-design/ui';
import { ref } from 'vue';

const visible = ref(true);
</script>

<template>
  <div>
    <Alert v-if="visible" title="Alert Message Text" type="success" closable @after-close="visible = false" />
    <p>The after-close event runs after the owned alert finishes closing.</p>
    <Button v-if="!visible" @click="visible = true">Show alert again</Button>
  </div>
</template>
```

## 语义化的 DOM 结构样式 (style-class)

通过 `classNames` 和 `styles` 传入对象/函数可以自定义 Alert 的语义化结构样式。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo（antd 的 createStaticStyles 直接换成对象/函数两态）

import type { AlertSemanticStyles } from '@apollo-design/ui';
import { Alert, Button } from '@apollo-design/ui';

const classNames = { root: 'demo-alert-root' };

const styleFn = ({ props }: { props: { type?: string } }): AlertSemanticStyles => {
  if (props.type === 'success') {
    return {
      root: {
        backgroundColor: 'rgba(82, 196, 26, 0.1)',
        borderColor: '#b7eb8f',
      },
      icon: { color: '#52c41a' },
    };
  }
  if (props.type === 'warning') {
    return {
      root: {
        backgroundColor: 'rgba(250, 173, 20, 0.1)',
        borderColor: '#ffe58f',
      },
      icon: { color: '#faad14' },
    };
  }
  return {};
};
</script>

<template>
  <div class="demo-alert-style-list">
    <Alert
      show-icon
      :class-names="classNames"
      title="Object styles"
      type="info"
      :styles="{ icon: { fontSize: '18px' }, section: { fontWeight: 500 } }"
    >
      <template #action>
        <Button size="small">Action</Button>
      </template>
    </Alert>
    <Alert
      show-icon
      :class-names="classNames"
      title="Function styles"
      type="success"
      :styles="styleFn"
    />
  </div>
</template>

<style scoped>
.demo-alert-style-list {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
</style>

<style>
.demo-alert-root {
  border: 2px dashed #ccc;
  border-radius: 8px;
  padding: 12px;
}
</style>
```

## 标题对齐 (custom-title-alignment)

未设置 `description` 时，Alert 会让图标、内容、操作区和关闭按钮作为整体垂直居中。
若标题可能换行并希望元素与标题首行对齐，可以通过语义化 `styles` 自行调整。

### custom-title-alignment.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 custom-title-alignment demo
// ⚠️ 内联样式数字必须转 px 字符串（Vue patchStyle 不转换，坑 #1）
import { Alert, Button } from '@apollo-design/ui';

const titleLineHeight = 22;
const iconSize = 14;
const closeIconSize = 12;
const smallButtonHeight = 24;

const firstLineStyles = {
  root: { alignItems: 'flex-start' },
  icon: { marginBlockStart: `${(titleLineHeight - iconSize) / 2}px` },
  actions: { marginBlockStart: `${(titleLineHeight - smallButtonHeight) / 2}px` },
  close: { marginBlockStart: `${(titleLineHeight - closeIconSize) / 2}px` },
};
</script>

<template>
  <Alert
    style="width: 360px; max-width: 100%"
    title="Long alert title wraps to multiple lines when the alert container is narrow enough."
    type="info"
    show-icon
    closable
    :styles="firstLineStyles"
  >
    <template #action>
      <Button size="small" type="text">Action</Button>
    </template>
  </Alert>
</template>
```

## 轮播的公告 (loop-banner)

配合跑马灯实现消息轮播通知栏（antd 用 react-fast-marquee，这里用等价 CSS 动画）。

### loop-banner.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 loop-banner demo
// ⚠️ antd 用 react-fast-marquee —— 我们用等价的 CSS 跑马灯动画（PLATFORM 替换，
//    见 README §5），API 面（banner + title 插槽）逐字对齐。
import { Alert } from '@apollo-design/ui';
</script>

<template>
  <Alert banner>
    <template #title>
      <div class="demo-alert-marquee">
        <span class="demo-alert-marquee-inner">
          I can be a Vue component, multiple Vue components, or just some text.&nbsp;&nbsp;&nbsp;&nbsp;I
          can be a Vue component, multiple Vue components, or just some
          text.&nbsp;&nbsp;&nbsp;&nbsp;
        </span>
      </div>
    </template>
  </Alert>
</template>

<style scoped>
.demo-alert-marquee {
  overflow: hidden;
  white-space: nowrap;
}
.demo-alert-marquee-inner {
  display: inline-block;
  animation: demo-alert-marquee-scroll 20s linear infinite;
}
@keyframes demo-alert-marquee-scroll {
  0% {
    transform: translateX(0);
  }
  100% {
    transform: translateX(-50%);
  }
}
@media (prefers-reduced-motion: reduce) {
  .demo-alert-marquee-inner { animation: none; }
}
</style>
```

## 错误边界 (error-boundary)

以 Vue `onErrorCaptured` 捕获实际后代的渲染、setup、生命周期及所属事件错误；边界自身和脱离 Vue 调用链的错误不属于此边界。示例切换后代的渲染状态后抛错，以父级 key 重新挂载边界恢复内容，不新增 reset 方法。

### error-boundary.vue

```vue
<script setup lang="ts">
import { AlertErrorBoundary, Button, Space } from '@apollo-design/ui';
import { defineComponent, h, ref } from 'vue';

const failed = ref(false);
const boundaryKey = ref(0);
const Content = defineComponent({
  props: { failed: Boolean },
  setup(props) {
    return () => {
      if (props.failed) throw new Error('The task panel could not render');
      return h('p', 'The task panel is ready.');
    };
  },
});
const reset = () => {
  failed.value = false;
  boundaryKey.value += 1;
};
</script>

<template>
  <div>
    <Space wrap>
    <Button danger @click="failed = true">Fail descendant render</Button>
    <Button @click="reset">Remount boundary</Button>
    </Space>
    <AlertErrorBoundary :key="boundaryKey"><Content :failed="failed" /></AlertErrorBoundary>
  </div>
</template>
```

## 内容插槽优先级 (content-slots)

同名 slot 存在时优先于内容 prop，明确空内容不会回退。移除条件 slot 后恢复 prop。Alert 的 title/description 与 CollapsePanel 的 header 使用同一存在优先规则；面板标题视觉为空时保留 Toggle panel 的可访问名称，切换标题不会重建面板中的输入状态。

A present slot overrides its content prop, including intentionally empty content. Removing a conditional slot restores the prop. Alert title/description and CollapsePanel header follow the same presence rule; the visually empty panel header retains an accessible Toggle panel name, and header changes preserve panel input state.

### content-slots.vue

```vue
<script setup lang="ts">
import { Alert, Button, Collapse, CollapsePanel, Flex, Input } from '@apollo-design/ui';
import { ref } from 'vue';

const show = ref(true);
const empty = ref(false);
const label = ref('Template content');
</script>

<template>
  <Flex vertical gap="small">
    <Flex gap="small" wrap>
      <Button @click="show = !show">切换插槽 / Toggle slots</Button>
      <Button @click="empty = !empty">切换空内容 / Toggle empty</Button>
      <Button @click="label = 'Updated content'">更新内容 / Update content</Button>
    </Flex>
    <Alert title="Prop title" description="Prop description">
      <template v-if="show" #title><strong v-if="!empty">{{ label }}</strong></template>
      <template v-if="show" #description><span v-if="!empty">{{ label }}</span></template>
    </Alert>
    <Collapse :default-active-key="['one']">
      <CollapsePanel key="one" header="Prop header">
        <template v-if="show" #header><strong v-if="!empty">{{ label }}</strong><span v-else class="alert-demo-panel-name">Toggle panel</span></template>
        <label>Panel state <Input aria-label="Panel state" /></label>
      </CollapsePanel>
    </Collapse>
  </Flex>
</template>

<style scoped>
.alert-demo-panel-name {
  position: absolute;
  width: 1px;
  height: 1px;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
}
</style>
```

## 组件 Token (component-token)

通过当前 `theme.components.Alert` 设置圆角、普通内边距、带描述内边距和描述图标尺寸。切换回默认值时移除覆盖，输入值与焦点随原生节点保留。根元素显式 `--apollo-alert-*` 变量仍优先于 Provider；默认与紧凑算法的内边距来自当前 Alias Token。

Use the current `theme.components.Alert` values for all four tokens. Removing the overrides restores the source theme without remounting the editor. Explicit root CSS variables take precedence over Provider tokens.

### component-token.vue

```vue
<script setup lang="ts">
import { Alert, Button, ConfigProvider, Input } from '@apollo-design/ui';
import { ref } from 'vue';

const custom = ref(true);
const draft = ref('Saved business draft');
</script>

<template>
  <div class="alert-component-token-demo">
    <Button @click="custom = !custom">{{ custom ? 'Use defaults' : 'Use custom tokens' }}</Button>
    <ConfigProvider :theme="custom ? { components: { Alert: {
      borderRadius: 16,
      defaultPadding: '12px 20px',
      withDescriptionPadding: '16px 20px',
      withDescriptionIconSize: 28,
    } } } : undefined">
      <Alert show-icon type="success" title="Current border radius and padding" />
      <Alert show-icon type="info" title="Current description spacing">
        <template #description>
          <label>Business draft <Input v-model:value="draft" aria-label="Alert theme draft" /></label>
        </template>
      </Alert>
    </ConfigProvider>
  </div>
</template>

<style scoped>
.alert-component-token-demo { display: flex; flex-direction: column; gap: 16px; }
</style>
```

---

# Anchor

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/anchor


# Anchor 锚点

使用原生链接展示目录，并根据实际滚动容器中的小节位置更新高亮。支持 items 数据和 Vue 默认槽组合，两者共享同一滚动、指示条及 Affix 链。

```vue
<Anchor :get-container="() => scrollArea" :affix="false" @click="onClick" @change="onChange">
  <AnchorLink href="#intro">
    <template #title><strong>介绍</strong></template>
    <AnchorLink href="#details" title="详情" />
  </AnchorLink>
</Anchor>
```

## Anchor Props

| Prop | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| items | 递归链接数据；存在默认槽时由槽覆盖，空槽也会有意盖住数据 | AnchorLinkItemProps[] | — |
| direction | 导航排列方向 | vertical \| horizontal | vertical |
| offsetTop | Affix 顶部偏移及 wrapper 最大高度计算，也作为滚动偏移后备 | number | — |
| bounds | 当前位置命中容差 | number | 5 |
| targetOffset | 滚动落点及当前位置检测偏移，优先于 offsetTop | number | — |
| affix | 是否使用 Affix；对象配置保留动态 offsetBottom/prefixCls | boolean \| AnchorAffixConfig | true |
| showInkInFixed | 非 Affix 模式仍显示指示条 | boolean | false |
| getContainer | 当前实际滚动容器；未传依次取 Provider.getTargetContainer 和 window | () => HTMLElement \| Window \| null \| undefined | — |
| getCurrentAnchor | 纯高亮映射，接收原始 href，移除后恢复原始值；不改事件载荷 | (activeLink: string) => string | — |
| replace | 使用 replaceState；单条链接配置优先 | boolean | false |
| prefixCls | 当前组件前缀，也作为 Link 的默认前缀 | string | apollo-anchor |
| classNames | root/item/itemTitle/indicator 语义类名，或接收 { props } 的函数 | AnchorSemanticClassNames \| function | — |
| styles | 同名语义样式，使用 Vue CSSProperties，或接收 { props } 的函数 | AnchorSemanticStyles \| function | — |

getContainer 返回空值表示 pending，清除旧滚动监听和活动检测，不回退 window。响应式模板 ref、Provider 替换和偏移变化均重新同步当前链路。

## 所属事件

| 组件/事件 | 载荷 | 说明 |
| --- | --- | --- |
| Anchor change | currentActiveLink: string | 原始 href；映射仅影响高亮，不改该载荷 |
| Anchor click | event: MouseEvent, link: AnchorLinkInfo | 选择、滚动及历史记录操作前通知 |
| AnchorLink click | event: MouseEvent, link: AnchorLinkInfo | 当前链接的同一原生事件，先于 Anchor 汇总通知 |

`link` 包含 `{ href, title }`，title 保留完整内容。任意 click 监听器调用 `preventDefault()` 都会取消默认选择、滚动与历史操作。只通过 emits 通知，不重复手调同名监听器；模板用 `@click`/`@change`，程序调用仍使用自然的 onClick/onChange listener。

修饰键、非主按钮、download、新浏览上下文及真正外链保持浏览器原生路径。普通同页片段使用所属文档解析，支持鼠标和原生 Enter 激活；不会引入额外箭头键或焦点模型。显式 replace 对同页片段使用 replaceState，对普通外部 URL 保留 location.replace 行为。

## 数据项、Link 与插槽

| 数据字段 | 说明 |
| --- | --- |
| key | items 中必需的 string/number 业务 key |
| href | 必需的原生链接地址 |
| title | items 中必需的 VNodeChild，支持 0、空值、数组和组件节点 |
| target | 原生 a.target |
| className | 数据项及 Link 的既有 item 类名 |
| replace | 覆盖 Anchor 的历史替换配置 |
| targetOffset | 单条滚动与检测偏移，优先于组件偏移 |
| prefixCls | 单条 Link 的显式前缀 |
| children | 仅 items 数据使用的递归子项；水平导航不渲染嵌套项 |

AnchorLink（也可使用 Anchor.Link）的 href 必需，title 数据可选，以支持原生 #title。没有 children prop，子链接通过默认槽表达。

| 组件/槽 | 职责 |
| --- | --- |
| Anchor default | 合法 Vue 链接组合，存在即优先于 items；条件空槽不会退回数据 |
| AnchorLink title | 实际 a 的完整内容，存在即覆盖 title 数据，含空槽和 0 |
| AnchorLink default | 嵌套子链接，沿用垂直导航职责 |

Anchor 与 Link 没有公开实例控制 API，不新增 v-model。Affix 保留自己的 change 与 updatePosition 职责。

## 原生 attrs、Provider 与 Token

Anchor 原生 attrs/class/style 落实际 wrapper（不落外层 Affix），合并 Provider → 当前组件语义样式 → 原生 attrs。Link 的 class/style/data/id 等既有根 attrs 保留在 item wrapper；aria-*、tabindex、focus/keyboard 原生监听落可操作的 a。活跃链接默认带 `aria-current="location"`。条件内容、同 key 数据替换与配置变化保留原节点和焦点。

当前 Provider 的前缀、方向、组件配置与主题动态生效。Link 默认继承 Anchor 当前前缀，显式 Link 前缀仍优先；方向通过原生 dir 消费，逻辑 CSS 随之更新。两个组件 Token 是 linkPaddingBlock（默认 paddingXXS）和 linkPaddingInlineStart（默认 padding），投影到实际消费层；替换、撤除和显式 0 均可用，既有全局别名继续参与派生。

## 资源与迁移

监听只在挂载后存在；滚动动画在新目标、配置变更、换容器和卸载时取消。链接注册按实例归属，重复 href 的一个实例移除不会删除其它实例。指示条跟随当前方向、内容与真实尺寸更新，观察和帧在卸载释放；SSR 不启动浏览器副作用。没有新增无信号位置轮询、路由适配或受控高亮模型。

onClick/onChange 迁为 owned emits；删除关于“多参数不能 emits”的旧判断。默认槽不再因上游习惯发弃用告警；原 children 伪 prop 使用默认槽，内容使用 #title。自定义 Anchor 前缀现在同时控制 Link 默认类名，以保证指示条链一致。历史 DOM 参考保留，只精确登记这条前缀及原生 dir 差异。

## Demo

basic、horizontal、onChange、onClick、replace、target-offset、target-offset-per-link、customize-highlight、static、style-class、component-token、bounds。组件 Token Demo 使用真实 ConfigProvider.components.Anchor。


## 组件 Token (component-token)

通过包裹类覆盖 `--apollo-anchor-link-padding-block` 与 `--apollo-anchor-link-padding-inline-start`，切换密度即可实时调整锚点链接的内边距。

### component-token.vue

```vue
<script setup lang="ts">
import type { AnchorLinkItemProps } from '@apollo-design/ui';
import { Anchor, ConfigProvider, Select, Space, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const defaultDensity = { value: 'default', label: '默认', block: 4, inline: 16 };
const densities = [
  { value: 'compact', label: '紧凑', block: 1, inline: 8 },
  defaultDensity,
  { value: 'spacious', label: '宽松', block: 10, inline: 28 },
];

type DensityValue = (typeof densities)[number]['value'];

const density = ref<DensityValue>('default');
const activeLink = ref('');

const currentDensity = computed(
  () => densities.find((item) => item.value === density.value) ?? defaultDensity,
);

const sections = [
  { key: 'a', title: 'Section A' },
  { key: 'b', title: 'Section B' },
  { key: 'c', title: 'Section C' },
];

const items: AnchorLinkItemProps[] = sections.map((section) => ({
  key: section.key,
  href: `#anchor-token-${section.key}`,
  title: section.title,
}));

const scrollArea = ref<HTMLElement | null>(null);

function getContainer(): HTMLElement | null {
  return scrollArea.value;
}

function onDensityChange(value: unknown): void {
  const selected = densities.find((item) => item.value === value);
  if (selected) density.value = selected.value;
}

function onChange(link: string): void {
  activeLink.value = link;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>链接内边距</span>
      <Select
        :value="density"
        :options="densities"
        style="width: 140px"
        @change="onDensityChange"
      />
      <Tag color="blue">block: {{ currentDensity.block }}px</Tag>
      <Tag>inline-start: {{ currentDensity.inline }}px</Tag>
      <Tag>当前高亮：{{ activeLink || '无' }}</Tag>
    </Space>

    <ConfigProvider :theme="{ components: { Anchor: { linkPaddingBlock: currentDensity.block, linkPaddingInlineStart: currentDensity.inline } } }">
    <div style="display: flex; gap: 16px">
      <Anchor
        class="anchor-token-demo"
        :items="items"
        :affix="false"
        :get-container="getContainer"
        :target-offset="8"
        @change="onChange"
      />
      <div ref="scrollArea" class="anchor-token-demo-scroll">
        <div
          v-for="section in sections"
          :id="`anchor-token-${section.key}`"
          :key="section.key"
          class="anchor-token-demo-section"
        >
          Section {{ section.key.toUpperCase() }}
        </div>
      </div>
    </div>
    </ConfigProvider>
  </div>
</template>

<style>
.anchor-token-demo-scroll {
  flex: 1;
  min-width: 0;
  height: 240px;
  overflow: auto;
  padding-inline: 8px;
  border: 1px solid var(--apollo-color-border);
  border-radius: var(--apollo-border-radius-lg);
}

.anchor-token-demo-section {
  height: 180px;
  margin-bottom: 16px;
  padding: 12px;
  background: var(--apollo-color-fill-quaternary);
  border-radius: var(--apollo-border-radius);
}
</style>
```

## 边界阈值 (bounds)

通过 `bounds` 调整锚点命中的顶部容差，配合 `getContainer` 指定内层滚动容器，滚动时即可观察高亮变化。

### bounds.vue

```vue
<script setup lang="ts">
import type { AnchorLinkItemProps } from '@apollo-design/ui';
import { Anchor, Select, Space, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const bounds = ref(5);
const activeLink = ref('');
const scrollArea = ref<HTMLElement | null>(null);

const boundsOptions = [
  { value: 0, label: '0 px' },
  { value: 5, label: '5 px（默认）' },
  { value: 20, label: '20 px' },
  { value: 60, label: '60 px' },
];

const sections = [
  { key: 'a', title: 'Section A' },
  { key: 'b', title: 'Section B' },
  { key: 'c', title: 'Section C' },
  { key: 'd', title: 'Section D' },
];

const items: AnchorLinkItemProps[] = sections.map((section) => ({
  key: section.key,
  href: `#anchor-bounds-${section.key}`,
  title: section.title,
}));

function getContainer(): HTMLElement | null {
  return scrollArea.value;
}

function onBoundsChange(value: unknown): void {
  bounds.value = Number(value);
}

function onChange(link: string): void {
  activeLink.value = link;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>bounds</span>
      <Select
        :value="bounds"
        :options="boundsOptions"
        style="width: 140px"
        @change="onBoundsChange"
      />
      <Tag color="blue">{{ bounds }} px</Tag>
      <Tag>当前高亮：{{ activeLink || '无' }}</Tag>
      <Tag>滚动容器内的锚点</Tag>
    </Space>

    <div style="display: flex; gap: 16px">
      <Anchor
        :items="items"
        :affix="false"
        :bounds="bounds"
        :get-container="getContainer"
        :target-offset="8"
        @change="onChange"
      />
      <div ref="scrollArea" class="anchor-bounds-demo-scroll">
        <div
          v-for="section in sections"
          :id="`anchor-bounds-${section.key}`"
          :key="section.key"
          class="anchor-bounds-demo-section"
        >
          Section {{ section.key.toUpperCase() }}
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.anchor-bounds-demo-scroll {
  flex: 1;
  min-width: 0;
  height: 240px;
  overflow: auto;
  padding-inline: 8px;
  border: 1px solid var(--apollo-color-border);
  border-radius: var(--apollo-border-radius-lg);
}

.anchor-bounds-demo-section {
  height: 180px;
  margin-bottom: 16px;
  padding: 12px;
  background: var(--apollo-color-fill-quaternary);
  border-radius: var(--apollo-border-radius);
}
</style>
```

## 静态锚点 (static)

设置 `affix={false}` 后锚点随文档流排列、不固钉，但仍会根据滚动容器高亮当前小节。

### static.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 static demo：affix=false，锚点随文档流排列、不固钉。
import { Anchor, type AnchorLinkItemProps } from '@apollo-design/ui';
import { ref } from 'vue';

const items: AnchorLinkItemProps[] = [
  { key: 'basic', href: '#anchor-static-basic', title: 'Basic demo' },
  { key: 'static', href: '#anchor-static-static', title: 'Static demo' },
  {
    key: 'api',
    href: '#anchor-static-api',
    title: 'API',
    children: [
      { key: 'props', href: '#anchor-static-props', title: 'Anchor Props' },
      { key: 'link-props', href: '#anchor-static-link-props', title: 'Link Props' },
    ],
  },
];

const sections = [
  { id: 'basic', title: 'Basic demo' },
  { id: 'static', title: 'Static demo' },
  { id: 'api', title: 'API' },
  { id: 'props', title: 'Anchor Props' },
  { id: 'link-props', title: 'Link Props' },
];

const scrollArea = ref<HTMLElement | null>(null);

const getContainer = (): HTMLElement | null => scrollArea.value;
</script>

<template>
  <div style="display: flex; gap: 16px">
    <Anchor
      :items="items"
      :affix="false"
      :get-container="getContainer"
      :target-offset="8"
    />
    <div ref="scrollArea" class="demo-anchor-static-scroll">
      <div
        v-for="section in sections"
        :id="`anchor-static-${section.id}`"
        :key="section.id"
        class="demo-anchor-static-section"
      >
        <h3 style="margin-top: 0">{{ section.title }}</h3>
        <p>静态锚点不会固定在视口上，滚动内容区域时高亮会跟随当前小节。</p>
      </div>
    </div>
  </div>
</template>

<style>
.demo-anchor-static-scroll {
  flex: 1;
  min-width: 0;
  height: 240px;
  overflow: auto;
  padding-inline: 16px;
  border: 1px solid var(--apollo-color-border);
  border-radius: var(--apollo-border-radius-lg);
}

.demo-anchor-static-section {
  height: 180px;
  margin-bottom: 16px;
  padding: 12px;
  background: var(--apollo-color-fill-quaternary);
  border-radius: var(--apollo-border-radius);
}
</style>
```

## 语义化样式 (style-class)

通过 `classNames` 定制锚点条目、标题与指示条，并用 `styles.itemTitle` 调整标题字距。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo：通过 classNames / styles 定制条目标题与指示条。
import { Anchor, type AnchorLinkItemProps } from '@apollo-design/ui';
import { ref } from 'vue';

const items: AnchorLinkItemProps[] = [
  { key: 'a', href: '#anchor-style-class-a', title: 'Section A' },
  { key: 'b', href: '#anchor-style-class-b', title: 'Section B' },
  { key: 'c', href: '#anchor-style-class-c', title: 'Section C' },
];

const classNames = {
  item: 'demo-anchor-style-item',
  itemTitle: 'demo-anchor-style-title',
  indicator: 'demo-anchor-style-indicator',
};

const styles = {
  itemTitle: { letterSpacing: '0.04em' },
};

const scrollArea = ref<HTMLElement | null>(null);

const getContainer = (): HTMLElement | null => scrollArea.value;
</script>

<template>
  <div style="display: flex; gap: 16px">
    <Anchor
      class="demo-anchor-style-root"
      :items="items"
      :affix="false"
      show-ink-in-fixed
      :get-container="getContainer"
      :target-offset="8"
      :class-names="classNames"
      :styles="styles"
    />
    <div ref="scrollArea" class="demo-anchor-style-scroll">
      <div
        v-for="section in ['a', 'b', 'c']"
        :id="`anchor-style-class-${section}`"
        :key="section"
        class="demo-anchor-style-section"
      >
        Section {{ section.toUpperCase() }}
      </div>
    </div>
  </div>
</template>

<style>
.demo-anchor-style-root .demo-anchor-style-title {
  color: var(--apollo-color-primary-text);
  font-weight: 600;
}

.demo-anchor-style-root .demo-anchor-style-item {
  border-radius: 6px;
  transition: background-color 0.3s;
}

.demo-anchor-style-root .demo-anchor-style-item:hover {
  background: var(--apollo-color-primary-bg);
}

.demo-anchor-style-root .demo-anchor-style-indicator {
  width: 4px;
  border-radius: 2px;
  background: var(--apollo-color-primary);
}

.demo-anchor-style-scroll {
  flex: 1;
  min-width: 0;
  height: 240px;
  overflow: auto;
  padding-inline: 8px;
  border: 1px solid var(--apollo-color-border);
  border-radius: var(--apollo-border-radius-lg);
}

.demo-anchor-style-section {
  height: 180px;
  margin-bottom: 16px;
  padding: 12px;
  background: var(--apollo-color-fill-quaternary);
  border-radius: var(--apollo-border-radius);
}
</style>
```

## basic (basic)

将锚点绑定到右侧独立滚动容器。点击 Section B/C 或滚动内容，观察定位和高亮。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo。⚠️ antd 用 `<div>` 做锚点目标 + 固定高度容器；
// 本仓同样用原生元素（demo 不引入未落地的组件）。
import { Anchor, type AnchorLinkItemProps } from '@apollo-design/ui';
import { ref } from 'vue';

const items: AnchorLinkItemProps[] = [
  { key: 'a', href: '#anchor-demo-a', title: 'Section A' },
  { key: 'b', href: '#anchor-demo-b', title: 'Section B' },
  { key: 'c', href: '#anchor-demo-c', title: 'Section C' },
];
const scrollArea = ref<HTMLElement | null>(null);
const getContainer = () => scrollArea.value;
</script>

<template>
  <div style="display: flex; gap: 16px">
    <Anchor :items="items" :affix="false" :get-container="getContainer" />
    <div ref="scrollArea" style="flex: 1; min-width: 0; height: 240px; overflow: auto" tabindex="0" aria-label="Anchor scroll content">
      <div
        v-for="id in ['a', 'b', 'c']"
        :id="`anchor-demo-${id}`"
        :key="id"
        style="height: 200px; margin-bottom: 16px; background: var(--apollo-color-fill-alter); color: var(--apollo-color-text); padding: 8px"
      >
        Section {{ id.toUpperCase() }}
      </div>
    </div>
  </div>
</template>
```

## customize-highlight (customize-highlight)

getCurrentAnchor 只改写高亮：始终突出 Section B，点击后仍滚动到真实目标。

### customize-highlight.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 customizeHighlight demo：`getCurrentAnchor` **改写高亮**
// （⚠️ 只改高亮，`onChange` 收到的仍是**原始 link**）。
import { Anchor, type AnchorLinkItemProps } from '@apollo-design/ui';
import { ref } from 'vue';

const items: AnchorLinkItemProps[] = [
  { key: 'a', href: '#anchor-customize-highlight-a', title: 'Section A' },
  { key: 'b', href: '#anchor-customize-highlight-b', title: 'Section B' },
  { key: 'c', href: '#anchor-customize-highlight-c', title: 'Section C' },
];

/** 永远把 `#anchor-customize-highlight-b` 显示为高亮。 */
const getCurrentAnchor = (): string => '#anchor-customize-highlight-b';
const scrollArea = ref<HTMLElement | null>(null);
const getContainer = () => scrollArea.value;
</script>

<template>
  <div style="display: flex; gap: 16px; min-width: 0">
    <Anchor :items="items" :affix="false" :get-container="getContainer" :get-current-anchor="getCurrentAnchor" />
    <div ref="scrollArea" style="flex: 1; min-width: 0; height: 240px; overflow: auto" tabindex="0" aria-label="Anchor scroll content">
      <section v-for="id in ['a', 'b', 'c']" :id="`anchor-customize-highlight-${id}`" :key="id" style="height: 200px; margin-bottom: 16px; padding: 12px; background: var(--apollo-color-fill-alter)">Section {{ id.toUpperCase() }}</section>
    </div>
  </div>
</template>
```

## horizontal (horizontal)

横向锚点配合独立滚动内容；点击各小节或手动滚动，观察底部指示条。

### horizontal.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 horizontal demo：`direction="horizontal"` ⇒ ink 变成底部横条。
import { Anchor, type AnchorLinkItemProps } from '@apollo-design/ui';
import { ref } from 'vue';

const items: AnchorLinkItemProps[] = [
  { key: 'a', href: '#anchor-horizontal-a', title: 'Section A' },
  { key: 'b', href: '#anchor-horizontal-b', title: 'Section B' },
  { key: 'c', href: '#anchor-horizontal-c', title: 'Section C' },
];
const scrollArea = ref<HTMLElement | null>(null);
const getContainer = () => scrollArea.value;
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; min-width: 0">
    <Anchor direction="horizontal" :items="items" :affix="false" :get-container="getContainer" />
    <div ref="scrollArea" style="flex: 0 0 auto; min-width: 0; height: 240px; overflow: auto" tabindex="0" aria-label="Anchor scroll content">
      <section v-for="id in ['a', 'b', 'c']" :id="`anchor-horizontal-${id}`" :key="id" style="height: 200px; margin-bottom: 16px; padding: 12px; background: var(--apollo-color-fill-alter)">Section {{ id.toUpperCase() }}</section>
    </div>
  </div>
</template>
```

## onChange (onChange)

滚动或点击当前示例内的锚点，读取真实 change 事件。每个示例使用独立的目标 ID。

### onChange.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 onChange demo：滚动时回调**当前锚点**。
import { Anchor, type AnchorLinkItemProps } from '@apollo-design/ui';
import { ref } from 'vue';

const items: AnchorLinkItemProps[] = [
  { key: 'a', href: '#anchor-onchange-a', title: 'Section A' },
  { key: 'b', href: '#anchor-onchange-b', title: 'Section B' },
  { key: 'c', href: '#anchor-onchange-c', title: 'Section C' },
];

const current = ref('');
const scrollArea = ref<HTMLElement | null>(null);
const getContainer = () => scrollArea.value;
</script>

<template>
  <div>
    <div style="margin-bottom: 8px">当前锚点：{{ current || '（无）' }}</div>
    <div style="display: flex; gap: 16px">
      <Anchor :items="items" :affix="false" :get-container="getContainer" @change="(link: string) => (current = link)" />
      <div ref="scrollArea" style="flex: 1; min-width: 0; height: 240px; overflow: auto" tabindex="0" aria-label="Anchor scroll content">
        <div
          v-for="id in ['a', 'b', 'c']"
          :id="`anchor-onchange-${id}`"
          :key="id"
          style="height: 200px; margin-bottom: 16px; background: var(--apollo-color-fill-alter); color: var(--apollo-color-text); padding: 8px"
        >
          Section {{ id.toUpperCase() }}
        </div>
      </div>
    </div>
  </div>
</template>
```

## onClick (onClick)

点击锚点记录链接信息，默认滚动与浏览器历史继续生效。业务需要拦截时可在回调内调用 preventDefault()。

### onClick.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 onClick demo：点击链接的回调（**自定义签名**，不是 DOM 事件）。
// ⚠️ 在回调里 `preventDefault()` 可以让组件**不接管 history**。
import { Anchor, type AnchorLinkInfo, type AnchorLinkItemProps } from '@apollo-design/ui';
import { ref } from 'vue';

const items: AnchorLinkItemProps[] = [
  { key: 'a', href: '#anchor-onclick-a', title: 'Section A' },
  { key: 'b', href: '#anchor-onclick-b', title: 'Section B' },
];

const clicked = ref('');

const handleClick = (e: MouseEvent, link: AnchorLinkInfo): void => {
  clicked.value = `${link.href}`;
  // 这里**不** preventDefault ⇒ 组件照常接管 history
  void e;
};
const scrollArea = ref<HTMLElement | null>(null);
const getContainer = () => scrollArea.value;
</script>

<template>
  <div>
    <div style="margin-bottom: 8px">最近点击：{{ clicked || '（无）' }}</div>
    <div style="display: flex; gap: 16px; min-width: 0">
    <Anchor :items="items" :affix="false" :get-container="getContainer" @click="handleClick" />
    <div ref="scrollArea" style="flex: 1; min-width: 0; height: 240px; overflow: auto" tabindex="0" aria-label="Anchor scroll content">
      <section v-for="id in ['a', 'b']" :id="`anchor-onclick-${id}`" :key="id" style="height: 200px; margin-bottom: 16px; padding: 12px; background: var(--apollo-color-fill-alter)">Section {{ id.toUpperCase() }}</section>
    </div>
  </div>
  </div>
</template>
```

## replace (replace)

点击示例内锚点时使用 replaceState；后退返回上一页而不是上一个锚点。

### replace.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 replace demo：用 `replaceState` 而不是 `pushState`。
import { Anchor, type AnchorLinkItemProps } from '@apollo-design/ui';
import { ref } from 'vue';

const items: AnchorLinkItemProps[] = [
  { key: 'a', href: '#anchor-replace-a', title: 'Section A' },
  { key: 'b', href: '#anchor-replace-b', title: 'Section B' },
];
const scrollArea = ref<HTMLElement | null>(null);
const getContainer = () => scrollArea.value;
</script>

<template>
  <div style="display: flex; gap: 16px; min-width: 0">
    <Anchor replace :items="items" :affix="false" :get-container="getContainer" />
    <div ref="scrollArea" style="flex: 1; min-width: 0; height: 240px; overflow: auto" tabindex="0" aria-label="Anchor scroll content">
      <section v-for="id in ['a', 'b']" :id="`anchor-replace-${id}`" :key="id" style="height: 200px; margin-bottom: 16px; padding: 12px; background: var(--apollo-color-fill-alter)">Section {{ id.toUpperCase() }}</section>
    </div>
  </div>
</template>
```

## target-offset (target-offset)

目标滚动到容器顶部下方 60px；targetOffset 优先于 offsetTop。

### target-offset.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 targetOffset demo：滚动落点的偏移（优先于 `offsetTop`）。
import { Anchor, type AnchorLinkItemProps } from '@apollo-design/ui';
import { ref } from 'vue';

const items: AnchorLinkItemProps[] = [
  { key: 'a', href: '#anchor-target-offset-a', title: 'Section A' },
  { key: 'b', href: '#anchor-target-offset-b', title: 'Section B' },
  { key: 'c', href: '#anchor-target-offset-c', title: 'Section C' },
];
const scrollArea = ref<HTMLElement | null>(null);
const getContainer = () => scrollArea.value;
</script>

<template>
  <div style="display: flex; gap: 16px">
    <Anchor :items="items" :affix="false" :get-container="getContainer" :target-offset="60" />
    <div ref="scrollArea" style="flex: 1; min-width: 0; height: 240px; overflow: auto" tabindex="0" aria-label="Anchor scroll content">
      <div
        v-for="id in ['a', 'b', 'c']"
        :id="`anchor-target-offset-${id}`"
        :key="id"
        style="height: 200px; margin-bottom: 16px; background: var(--apollo-color-fill-alter); color: var(--apollo-color-text); padding: 8px"
      >
        Section {{ id.toUpperCase() }}
      </div>
    </div>
  </div>
</template>
```

## target-offset-per-link (target-offset-per-link)

每条链接独立设置 targetOffset，点击小节比较 0、120 与 60px 的落点。

### target-offset-per-link.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 targetOffset-per-link demo：**每条链接**自己的滚动偏移
// （优先级高于 `Anchor` 的全局 `targetOffset`）。
import { Anchor, type AnchorLinkItemProps } from '@apollo-design/ui';
import { ref } from 'vue';

const items: AnchorLinkItemProps[] = [
  { key: 'a', href: '#anchor-target-offset-per-link-a', title: 'Section A', targetOffset: 0 },
  { key: 'b', href: '#anchor-target-offset-per-link-b', title: 'Section B', targetOffset: 120 },
  { key: 'c', href: '#anchor-target-offset-per-link-c', title: 'Section C', targetOffset: 60 },
];
const scrollArea = ref<HTMLElement | null>(null);
const getContainer = () => scrollArea.value;
</script>

<template>
  <div style="display: flex; gap: 16px">
    <Anchor :items="items" :affix="false" :get-container="getContainer" />
    <div ref="scrollArea" style="flex: 1; min-width: 0; height: 240px; overflow: auto" tabindex="0" aria-label="Anchor scroll content">
      <div
        v-for="id in ['a', 'b', 'c']"
        :id="`anchor-target-offset-per-link-${id}`"
        :key="id"
        style="height: 200px; margin-bottom: 16px; background: var(--apollo-color-fill-alter); color: var(--apollo-color-text); padding: 8px"
      >
        Section {{ id.toUpperCase() }}
      </div>
    </div>
  </div>
</template>
```

---

# App

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/app


为子树提供独立的 Message、Notification 和 Modal 服务，并为页面提供统一根样式。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/app/demo)：获取三个服务，以及替换当前消息和通知默认配置。

## API

| Prop | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | 当前宿主的类名前缀 | `string` | `apollo-app` |
| component | 原生宿主；`false` 时只渲染内容及服务 holder | `'div' \| 'section' \| 'main' \| 'span' \| false` | `'div'` |
| message | Message hook 配置，沿嵌套 App 合并 | `MessageConfigOptions` | — |
| notification | Notification hook 配置，沿嵌套 App 合并 | `NotificationConfig` | — |

默认槽接受完整 Vue 内容，保留 `0`、数组、条件内容和显式空内容。App 没有所属事件、v-model 或命令式组件 ref 方法。根 `class`、`style`、原生属性及事件监听器作用于实际宿主；Provider 的 `components.app.className/style` 先合并，局部原生样式优先。

`component=false` 没有 attrs 落点，开发期会对已传入的原生 attrs 给出诊断，不将它们挪到子节点或浮层。改变宿主遵循 Vue 的原生子树替换规则；三个服务的 holder 是宿主的稳定同级节点，不随宿主替换。

### useApp

在 App **后代组件的 setup** 中调用具名 `useApp()` 或 `App.useApp()`：

```ts
const { message, notification, modal } = App.useApp();
const close = message.loading('处理中', 0);
close.then((terminated) => console.log(terminated));
const confirm = modal.confirm({ title: '确认操作？' });
confirm.then((accepted) => console.log(accepted));
```

返回对象的实际类型为 `UseAppProps`：`message: MessageInstance`、`notification: NotificationInstance`、`modal: ModalHookAPI`。服务方法与各自 hook 相同，支持其真实返回值和业务回调。后代 setup 中的提前调用由各自 holder 队列接收。每个 App 拥有独立实例，嵌套 App 使用最近的 provider；App 卸载时终止其工作并释放浮层及资源。

没有 App provider 或 Vue 注入上下文时，`useApp()` 明确抛出 `[Apollo App] useApp() requires an App provider.`，不再返回假空 API。调用位置应在后代 setup，不能在创建 App 的父组件 setup 中读取尚不存在的子级 provider。

### 配置、主题与迁移

`message`、`notification` 分别按字段浅合并父 App 和本地对象，本地字段优先。替换配置会移除旧对象独有字段；撤除本地 prop 会恢复父 App 的当前配置。注入对象引用保持稳定，后代和 holder 都读取当前配置。已有消息的具体更新职责以相应服务 API 为准。

App 没有自有 Component Token，样式消费全局 `colorText`、`fontSize`、`lineHeight`、`fontFamily` 变量；当前 Provider 的方向、前缀及样式替换和撤除都会反映到宿主。

旧文档中的 `className/rootClassName` 改用原生 `class`；`style` 使用原生 StyleValue。AppConfig 和 useApp 不再使用任意字段或占位方法类型。导出 `AppProps`、`AppComponentType`、`AppConfig`、`AppSlots`、`UseAppProps`。


## basic (basic)

获取 `message`、`notification`、`modal` 实例。

### basic.vue

```vue
<script setup lang="ts">
// Services belong to the nearest App and are released when it unmounts.
import { App, Button, Space } from '@apollo-design/ui';
import { h } from 'vue';

const Page = {
  setup() {
    const { message, modal, notification } = App.useApp();
    return () =>
      h(Space, { wrap: true }, () => [
        h(
          Button,
          { type: 'primary', onClick: () => message.success('Success!') },
          () => 'Open message',
        ),
        h(
          Button,
          {
            type: 'primary',
            onClick: () => modal.warning({ title: 'This is a warning message' }),
          },
          () => 'Open modal',
        ),
        h(
          Button,
          {
            type: 'primary',
            onClick: () =>
              notification.info({ title: 'Notification topLeft', placement: 'topLeft' }),
          },
          () => 'Open notification',
        ),
      ]);
  },
};
</script>

<template>
  <App>
    <Page />
  </App>
</template>
```

## config (config)

对 `message`、`notification` 进行配置。切换默认值后继续使用同一组 App 服务。

### config.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/config.tsx —— AppConfig 沿树合并（message/notification 配置）。
import { App, Button, Space } from '@apollo-design/ui';
import { h, ref } from 'vue';

const limited = ref(true);

const Page = {
  setup() {
    const { message, notification } = App.useApp();
    return () =>
      h(Space, { wrap: true }, () => [
        h(
          Button,
          { type: 'primary', onClick: () => message.success('Success!') },
          () => 'Message for only one',
        ),
        h(
          Button,
          {
            type: 'primary',
            onClick: () => notification.info({ title: 'Notification' }),
          },
          () => 'Notification for bottomLeft',
        ),
      ]);
  },
};
</script>

<template>
  <App
    :message="{ maxCount: limited ? 1 : 2 }"
    :notification="{ placement: limited ? 'bottomLeft' : 'topLeft' }"
  >
    <Button style="margin-bottom: 12px" @click="limited = !limited">Change current defaults</Button>
    <Page />
  </App>
</template>
```

---

# AutoComplete

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/auto-complete


可自由输入文本，并从候选中选择的自动完成输入框。候选、键盘、无障碍与主题由 Select 共享引擎负责。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/auto-complete/demo)。基础示例包含三个模型与键盘回填；候选支持当前条件选项和自定义内容。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value / defaultValue | 受控值 / 初值；支持 `v-model:value`，输入和选择输出原始值 | `SelectValue` | — |
| searchValue | 搜索词；支持 `v-model:search-value` | `string` | `''` |
| open / defaultOpen | 受控开合 / 初值；支持 `v-model:open` | `boolean` | `false` |
| options | 候选数据；显式 `[]` 也优先于选项插槽 | `DefaultOptionType[]` | — |
| dataSource | 已废弃；文本、`{ value, text? }` 或 Option/OptGroup VNode，保留已有映射 | `DataSourceItemType[]` | — |
| placeholder | 占位文本；富内容使用 `#placeholder` | `string` | — |
| allowClear | 清除按钮及图标/可访问名配置 | `SelectProps['allowClear']` | `false` |
| disabled / size / variant / status | 同 Select 的禁用、尺寸、变体与校验状态 | — | — |
| showSearch | 搜索算法配置；仅含 `filterOption/filterSort/optionFilterProp/autoClearSearchValue` | `boolean \| SelectSearchConfig` | `true` |
| filterOption | 过滤算法，第二参为实际候选；`false` 保留全部候选 | `boolean \| (text, option) => boolean` | — |
| defaultActiveFirstOption | 默认激活首项；`false` 时等待键盘或鼠标激活 | `boolean` | `true` |
| backfill | 键盘导航时预览候选值；Enter/Tab 或点击确认时提交，不因预览发送值或搜索通知 | `boolean` | `false` |
| autoFocus / maxLength / id / tabIndex | 实际输入框的自动聚焦、长度、标识与 Tab 顺序 | — | — |
| listHeight / listItemHeight / virtual | 候选列表尺寸和虚拟滚动 | 同 Select | — |
| popupMatchSelectWidth / placement / getPopupContainer | 浮层宽度、位置与容器（支持 ShadowRoot） | 同 Select | — |
| classNames / styles | 对象或 `({ props }) => 对象`；语义面为 `root/prefix/input/placeholder/content/clear/popup.{root,list,listItem}` | — | — |

受控更新是提议，父级拒绝后保持接受值，撤控保留最后接受值。键盘回填是临时预览：鼠标激活不回填；接受新值、输入、实际关闭、撤销 `backfill` 或禁用时清除。关闭再打开不会恢复旧预览。`0` 是有效候选值。

默认插槽在 render 中读取并分类，支持条件插槽、`v-if/v-for` 与动态分组；沿用已交付的选项缓存与响应性。`dataSource` 中的富文本是数据，顶层内容扩展使用插槽。单个自定义 input/textarea 仍未提供替换协议，会给出明确警告；当前没有 AutoComplete PurePanel 公共入口。

### Events

| 事件 | 参数与说明 |
|---|---|
| change / update:value | `(value, option)` / `(value)`；输入、选择或清除提交值 |
| search / update:searchValue | `(text: string)`；输入搜索通知 / 搜索模型提议，候选选择同步搜索模型；外部 value 的派生同步不重复通知 |
| select / deselect | `(value: string \| number, option)`；候选选择通知；combobox 没有多选取消操作 |
| openChange / update:open | `(open: boolean)`；开合通知与模型提议 |
| focus / blur | `(event: FocusEvent)`；实际控件焦点 |
| clear | 清除操作 |
| popupScroll / inputKeyDown | `(event: Event)` / `(event: KeyboardEvent)` |

通知使用 typed emits。`h()` 的 `onSearch/onChange` 等是 Vue 监听器属性，不再作为组件回调 Props 手动调用。`onDropdownVisibleChange` 直接迁为 `@openChange`；`showSearch.onSearch/searchValue/searchIcon` 分别迁为 `@search`、顶层搜索模型与 `#searchIcon`。

### Slots

`default`（Option/OptGroup 数据）、`prefix`、`placeholder`、`notFoundContent`、`clearIcon`、`loadingIcon`、`searchIcon`、`labelRender="{ value, label }"`、`optionRender="{ option, index }"`、`popupRender="{ menu }"`、`menuItemSelectedIcon="{ value, disabled, isSelected }"`、`suffixIcon="{ searchValue, open, focused, showSearch, loading }"`。

当前插槽动态转发，提供空插槽表示有意隐藏，数字 `0` 正常显示。未提供 suffix 插槽时默认无箭头；`#searchIcon/#loadingIcon` 在对应状态可单独定制。

### Attrs、Provider 与主题

原生 `class/style/data-*` 落选择器根，`id/tabindex/role/aria-*` 落实际输入框。attrs 在 render 中读取，类名合并一次，字符串/数组样式和移除均生效；透传不能覆盖内部 combobox 模式或通知处理。

当前 `components.autoComplete` 的类名、样式、语义与搜索/清除配置可响应式替换或移除；Select 与 AutoComplete 的专属组件配置相互隔离；全局尺寸、方向与 Form/Compact 上下文继续由共享引擎读取。主题完全使用 Select Token，根与 Teleport 浮层同步，无独立 AutoComplete Token。

### Expose

| 成员 | 说明 |
|---|---|
| focus(options?: FocusOptions) / blur() | 操作真实输入框 |
| scrollTo(arg?) | 数字为像素坐标；条目使用 `{ index?, key?, align? }`；已有 `{ top }` 坐标形态继续支持 |
| nativeElement | 真实选择器根 `HTMLElement \| null` |

保留的样式别名：`dropdownMatchSelectWidth` → `popupMatchSelectWidth`，`popupClassName/dropdownClassName` → `classNames.popup.root`，`dropdownStyle` → `styles.popup.root`。内容函数使用 `#popupRender` 等原生插槽。


## 自定义选项 (custom)

使用 `#optionRender` 插槽渲染带 `Tag` 的自定义选项，同时保留 AutoComplete 的输入与筛选。

### custom.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `custom` demo：通过 optionRender 插槽自定义选项内容。
import type { DefaultOptionType } from '@apollo-design/ui';
import { AutoComplete, Tag, Text } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
const options: DefaultOptionType[] = [
  { value: 'antd', label: 'Ant Design', category: 'React' },
  { value: 'apollo', label: 'Apollo Design', category: 'Vue' },
  { value: 'vue', label: 'Vue 3', category: 'Framework' },
];
</script>

<template>
  <div>
    <AutoComplete aria-label="自动补全输入框"
      v-model:value="value"
      :options="options"
      :filter-option="true"
      style="width: 280px"
      placeholder="输入以筛选"
    >
      <template #optionRender="{ option }">
        <div style="display: flex; align-items: center; justify-content: space-between; gap: 24px">
          <span>{{ option.label }}</span>
          <Tag color="blue">{{ option.data.category }}</Tag>
        </div>
      </template>
    </AutoComplete>
    <div style="margin-top: 8px"><Text type="secondary">当前值：{{ value || '（空）' }}</Text></div>
  </div>
</template>
```

## 表单禁用 (disabled-in-form)

`Form` 的 `disabled` 会级联禁用内部 `AutoComplete`，用 `Switch` 切换即可看到启用/禁用状态。

### disabled-in-form.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `disabled-in-form` demo：Form 级联禁用 AutoComplete。
import type { DefaultOptionType, SelectValue } from '@apollo-design/ui';
import { AutoComplete, Form, FormItem, Switch, Text } from '@apollo-design/ui';
import { reactive, ref } from 'vue';

const disabled = ref(true);
const formState = reactive({ fruit: '' });
const options: DefaultOptionType[] = [{ value: 'Apple' }, { value: 'Banana' }, { value: 'Cherry' }];

const onFruitChange = (value: SelectValue) => {
  formState.fruit = String(value ?? '');
};
</script>

<template>
  <div>
    <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 16px">
      <Text>Form disabled</Text>
      <Switch v-model:checked="disabled" aria-label="禁用表单" />
    </div>
    <Form :model="formState" :disabled="disabled" layout="vertical" style="max-width: 320px">
      <FormItem label="Fruit" name="fruit">
        <AutoComplete aria-label="自动补全输入框"
          :value="formState.fruit"
          :options="options"
          placeholder="选择或输入水果"
          @update:value="onFruitChange"
        />
      </FormItem>
      <FormItem label="当前值">
        <Text>{{ formState.fruit || '（空）' }}</Text>
      </FormItem>
    </Form>
  </div>
</template>
```

## 自定义清除 (customize-clear)

开启 `allowClear` 后用 `#clearIcon` 替换清除图标，`onClear` 回调实时统计清空次数。

### customize-clear.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `customize-clear` demo：自定义 clearIcon 并反馈清空次数。
import { CloseCircleFilled } from '@apollo-design/icons';
import type { DefaultOptionType } from '@apollo-design/ui';
import { AutoComplete, Text } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('Ant Design');
const cleared = ref(0);
const options: DefaultOptionType[] = [
  { value: 'Ant Design' },
  { value: 'Apollo Design' },
  { value: 'Vue 3' },
];

const onClear = () => {
  cleared.value += 1;
};
</script>

<template>
  <div>
    <AutoComplete aria-label="自动补全输入框"
      v-model:value="value"
      :options="options"
      allow-clear
      style="width: 280px"
      :on-clear="onClear"
    >
      <template #clearIcon><CloseCircleFilled style="color: #1677ff" /></template>
    </AutoComplete>
    <div style="margin-top: 8px">
      <Text type="secondary">已清空 {{ cleared }} 次；当前值：{{ value || '（空）' }}</Text>
    </div>
  </div>
</template>
```

## 自定义候选面板 (render-panel)

通过 `#popupRender` 拿到原始候选菜单 `menu`，在它前后追加面板标题、分隔线与关闭按钮。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 render-panel demo：在候选菜单前后插入自定义面板内容。
import type { DefaultOptionType } from '@apollo-design/ui';
import { AutoComplete, Button, Divider, Text } from '@apollo-design/ui';
import { defineComponent, h, type PropType, ref, type VNodeChild } from 'vue';

const value = ref('');
const open = ref(false);
const options = ref<DefaultOptionType[]>([]);

const onSearch = (text: string) => {
  options.value = text ? [{ value: text }, { value: `${text}${text}` }] : [];
};

/** demo 局部辅助：在模板里渲染一个 VNode（Vue 模板没有 h() 的直接入口）。 */
const RenderVNode = defineComponent({
  props: { node: { type: null as unknown as PropType<VNodeChild>, default: undefined } },
  setup: (props) => () => props.node,
});
</script>

<template>
  <div>
    <AutoComplete
      v-model:value="value"
      v-model:open="open"
      aria-label="自定义候选面板的自动补全"
      :options="options"
      placeholder="输入以生成候选"
      style="width: 280px"
      @search="onSearch"
    >
      <template #popupRender="{ menu }">
        <div>
          <div style="padding: 8px">Render Panel</div>
          <RenderVNode :node="menu" />
          <Divider style="margin: 0" />
          <Button type="text" block @mousedown.prevent @click="open = false">Close</Button>
        </div>
      </template>
    </AutoComplete>
    <div style="margin-top: 8px">
      <Text type="secondary">当前值：{{ value || '（空）' }}</Text>
    </div>
  </div>
</template>
```

## allow-clear (allow-clear)

`allowClear` 与自定义清除图标（`#clearIcon` 插槽）。

### allow-clear.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/allowClear.tsx
import { AutoComplete, Space } from '@apollo-design/ui';
</script>

<template>
  <Space vertical style="width: 100%">
    <AutoComplete aria-label="自动补全输入框"
      :options="[{ value: 'text' }]"
      placeholder="allowClear"
      style="width: 200px"
      allow-clear
    />
    <AutoComplete aria-label="自动补全输入框"
      :options="[{ value: 'text' }]"
      placeholder="clearIcon"
      style="width: 200px"
      allow-clear
      #clearIcon
    >
      <span>⨯</span>
    </AutoComplete>
  </Space>
</template>
```

## and-select (and-select)

AutoComplete 与 Select 组合使用（同一份 options 数据源）。

### and-select.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/AutoComplete-and-Select.tsx（AutoComplete 与 Select 组合）

import type { DefaultOptionType } from '@apollo-design/ui';
import { AutoComplete, Flex, Select } from '@apollo-design/ui';
import { ref } from 'vue';

const options = ref<DefaultOptionType[]>([]);
const handleSearch = (value: string) => {
  options.value = !value
    ? []
    : [{ value }, { value: value + value }, { value: value + value + value }];
};
</script>

<template>
  <Flex vertical gap="medium">
    <AutoComplete aria-label="自动补全输入框"
      style="width: 200px"
      @search="handleSearch"
      placeholder="try to type `b`"
      :options="options"
    />
    <Select aria-label="选项选择" style="width: 200px" placeholder="Select" :options="options" />
  </Flex>
</template>
```

## basic (basic)

不自定义过滤条件（`showSearch.onSearch` 驱动候选）+ 受控模式。

第二个输入使用三个模型；开启 `backfill` 后，键盘导航只预览候选，Enter/Tab 或点击确认时提交值。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic.tsx

import type { DefaultOptionType, SelectValue } from '@apollo-design/ui';
import { AutoComplete } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
const searchValue = ref('');
const open = ref(false);
const options = ref<DefaultOptionType[]>([]);
const anotherOptions = ref<DefaultOptionType[]>([]);

const getPanelValue = (searchText: string) =>
  !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)];

const mockVal = (str: string, repeat = 1) => ({ value: str.repeat(repeat) });

const onSelect = (data: string | number) => {
  console.log('onSelect', data);
};
const onChange = (data: SelectValue) => {
  value.value = String(data);
};
</script>

<template>
  <div>
    <AutoComplete aria-label="自动补全输入框"
      :options="options"
      style="width: 200px"
      @search="text => (options = getPanelValue(text))"
      placeholder="input here"
      @select="onSelect"
    />
    <br />
    <br />
    <AutoComplete aria-label="自动补全输入框"
      v-model:value="value"
      v-model:search-value="searchValue"
      v-model:open="open"
      backfill
      :options="anotherOptions"
      style="width: 200px"
      @search="text => (anotherOptions = getPanelValue(text))"
      placeholder="control mode"
      @select="onSelect"
      @change="onChange"
    />
    <p>Value: {{ value || '—' }} · Search: {{ searchValue || '—' }} · Open: {{ open }}</p>
  </div>
</template>
```

## certain-category (certain-category)

`showSearch.onSearch` 驱动候选更新（完成输入建议）。

### certain-category.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/certain-category.tsx

import type { DefaultOptionType } from '@apollo-design/ui';
import { AutoComplete } from '@apollo-design/ui';
import { ref } from 'vue';

const options = ref<DefaultOptionType[]>([]);
const handleSearch = (value: string) => {
  options.value =
    !value || value.includes('@')
      ? []
      : ['gmail.com', '163.com', 'qq.com'].map((domain) => ({
          label: `${value}@${domain}`,
          value: `${value}@${domain}`,
        }));
};
</script>

<template>
  <AutoComplete aria-label="自动补全输入框"
    style="width: 200px"
    @search="handleSearch"
    placeholder="input here"
    :options="options"
  />
</template>
```

## non-case-sensitive (non-case-sensitive)

不区分大小写的过滤（`filterOption` 自定义）。

### non-case-sensitive.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/non-case-sensitive.tsx

import type { DefaultOptionType } from '@apollo-design/ui';
import { AutoComplete } from '@apollo-design/ui';
import { ref } from 'vue';

const options = ref<DefaultOptionType[]>(
  ['.net', '.cpp', '.java', '.php'].map((ext) => ({
    value: ext,
  })),
);
</script>

<template>
  <AutoComplete aria-label="自动补全输入框"
    style="width: 200px"
    :options="options"
    placeholder="input here"
    :filter-option="(input, option) => String(option?.value ?? '').toUpperCase().includes(input.toUpperCase())"
  />
</template>
```

## options (options)

`options` 数据源（deprecated `ASelectOption` 子组件形态见 `AutoComplete.Option`）。

### options.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/options.tsx（ASelectOption 子组件形态）
import { AutoComplete } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
const options = ref(['Burns Bay Road', 'Downing Street', 'Wall Street']);
</script>

<template>
  <AutoComplete aria-label="自动补全输入框" v-model:value="value" style="width: 200px" :options="options.map((o) => ({ value: o }))" />
</template>
```

## status (status)

`status="error"` / `"warning"` 校验状态。

### status.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/status.tsx

import type { DefaultOptionType } from '@apollo-design/ui';
import { AutoComplete, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const options = ref<DefaultOptionType[]>([]);
const anotherOptions = ref<DefaultOptionType[]>([]);

const getPanelValue = (searchText: string) =>
  !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)];
const mockVal = (str: string, repeat = 1) => ({ value: str.repeat(repeat) });
</script>

<template>
  <Space vertical style="width: 100%">
    <AutoComplete aria-label="自动补全输入框"
      :options="options"
      @search="text => (options = getPanelValue(text))"
      status="error"
      style="width: 200px"
    />
    <AutoComplete aria-label="自动补全输入框"
      :options="anotherOptions"
      @search="text => (anotherOptions = getPanelValue(text))"
      status="warning"
      style="width: 200px"
    />
  </Space>
</template>
```

## style-class (style-class)

语义化 `classNames` / `styles`（对象式与函数式变体）。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx

import type { AutoCompleteProps } from '@apollo-design/ui';
import { AutoComplete, Flex } from '@apollo-design/ui';

const options: AutoCompleteProps['options'] = [
  { value: 'Burnaby' },
  { value: 'Seattle' },
  { value: 'Los Angeles' },
];

const stylesObject: AutoCompleteProps['styles'] = {
  popup: {
    root: { borderWidth: 1, borderColor: '#1890ff' },
    list: { backgroundColor: 'rgba(240,240,240, 0.85)' },
    listItem: { color: '#272727' },
  },
};

const stylesFn: AutoCompleteProps['styles'] = ({ props }: { props: AutoCompleteProps }) => {
  if (props.variant === 'filled') {
    return {
      popup: {
        root: { borderWidth: 1, borderColor: '#ccc' },
        list: { backgroundColor: 'rgba(240,240,240, 0.85)' },
        listItem: { color: '#272727' },
      },
    };
  }
  return {};
};
</script>

<template>
  <Flex vertical gap="medium">
    <AutoComplete aria-label="自动补全输入框" :options="options" style="width: 200px" placeholder="object styles" :styles="stylesObject" />
    <AutoComplete aria-label="自动补全输入框"
      :options="options"
      style="width: 200px"
      variant="filled"
      placeholder="function styles"
      :styles="stylesFn"
    />
  </Flex>
</template>
```

## uncertain-category (uncertain-category)

候选数量不确定（输入即搜索）。

### uncertain-category.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/uncertain-category.tsx

import type { DefaultOptionType } from '@apollo-design/ui';
import { AutoComplete } from '@apollo-design/ui';
import { ref } from 'vue';

const options = ref<DefaultOptionType[]>([]);
const handleSearch = (value: string) => {
  setOptions(
    !value ? [] : [value, value + value, value + value + value].map((v) => ({ value: v })),
  );
};
const setOptions = (o: DefaultOptionType[]) => {
  options.value = o;
};
</script>

<template>
  <AutoComplete aria-label="自动补全输入框"
    style="width: 200px"
    @search="handleSearch"
    placeholder="input here"
    :options="options"
  />
</template>
```

## variant (variant)

`outlined` / `filled` / `borderless` / `underlined` 四种变体。

### variant.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/variant.tsx

import type { DefaultOptionType } from '@apollo-design/ui';
import { AutoComplete, Flex } from '@apollo-design/ui';
import { ref } from 'vue';

const options = ref<DefaultOptionType[]>([]);
const getPanelValue = (searchText: string) =>
  !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)];
const mockVal = (str: string, repeat = 1) => ({ value: str.repeat(repeat) });
const onSearch = (text: string) => {
  options.value = getPanelValue(text);
};
</script>

<template>
  <Flex vertical gap="12px">
    <AutoComplete aria-label="自动补全输入框" :options="options" style="width: 200px" placeholder="Outlined" @search="onSearch" />
    <AutoComplete aria-label="自动补全输入框" :options="options" style="width: 200px" placeholder="Filled" variant="filled" @search="onSearch" />
    <AutoComplete aria-label="自动补全输入框" :options="options" style="width: 200px" placeholder="Borderless" variant="borderless" @search="onSearch" />
    <AutoComplete aria-label="自动补全输入框" :options="options" style="width: 200px" placeholder="Underlined" variant="underlined" @search="onSearch" />
  </Flex>
</template>
```

---

# Avatar

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/avatar


以图片、图标或字符代表用户或事物。静态头像不进入 Tab 顺序；有操作时由外层原生链接或按钮提供交互。

## 代码演示

十个示例覆盖尺寸/形状、类型、动态字符与留白、徽标、分组、溢出计数、图片失败、隐藏后显示、响应式尺寸及当前组件 Token。`max-count` 的开关控制可见名额是否包含溢出指示器，Group 的 `max.count` 本身始终只计算可见子项。

## Avatar Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | 本组件类名前缀 | `string` | 当前 ConfigProvider |
| shape | 本地形状优先于 Group | `'circle' \| 'square'` | Group → `'circle'` |
| size | 本地尺寸优先于 Group 和全局尺寸；响应式表取当前匹配且已配置的最大断点 | `SizeType \| 'default' \| number \| ScreenSizeMap` | Group → `componentSize` → `'medium'` |
| gap | 默认内容缩放时预留的左右空间，像素 | `number` | `4` |
| src | 字符串图片地址或完整 VNode 数据；图片失败后显示 icon/default | `VNodeChild` | — |
| srcSet | 原生图片 srcset，变化后会重试图片 | `string` | — |
| draggable | 原生图片拖拽属性 | `boolean \| 'true' \| 'false'` | — |
| icon | 图标 VNode 数据 | `VNodeChild` | — |
| alt | 原生图片替代文本；默认装饰图像，需表达身份时填写名称 | `string` | `''` |
| crossOrigin | 原生图片 crossorigin | `'' \| 'anonymous' \| 'use-credentials'` | — |
| beforeFallback | error 事件后同步调用；返回 false 保留失败图片 | `(event: Event) => boolean \| void` | — |

`class`、`style`、`id`、data/ARIA 和其他原生监听器落在稳定的 span 根；style 支持字符串、数组和对象，优先于尺寸、主题和 Provider 样式。文字内容在 SSR 即可见，挂载后随根和内容尺寸变化测量缩放。

## Slots / Events

| 插槽 | 内容 |
|---|---|
| image | 完整图片内容，存在时覆盖 src，包括有意为空的槽 |
| icon | 无图片时的完整图标内容，存在时覆盖 icon 数据，包括空槽 |
| default | 无图片/图标时的字符或完整业务内容 |

| 事件 | 载荷 | 说明 |
|---|---|---|
| click | 原生 `MouseEvent` | 根点击一次发出一次；支持 `.once` 和合并监听器 |
| error | 原生图片 `Event` | 加载失败时一次发出；监听器返回值不控制回退，取消使用 beforeFallback |

## AvatarGroup / Avatar.Group

两个入口指向同一个可安装组件。

| 参数 | 说明 | 类型 |
|---|---|---|
| prefixCls | 组类名前缀 | `string` |
| size | 经当前上下文传给子头像，支持数字、0和响应式表；子头像可覆盖 | `AvatarSize` |
| shape | 经当前上下文传给子头像 | `'circle' \| 'square'` |
| max | `{count?, style?, popover?}`：可见项数、指示器样式和 Popover 配置 | `AvatarGroupMax` |

`max.count` 不包含 `+N` 指示器，0/未设置/负数/非有限数不限量，正小数向下取整。默认槽的直接子项（含展开的 Fragment、忽略注释）参与计数；需要多头像时直接使用 `v-for`。不读取业务组件内部渲染结果。

溢出指示器拥有原生 button。默认保留 hover，同时支持点击和 Enter/Space；Escape 关闭并保留按钮焦点。显式 `focus` 和受控 `max.popover.open` 仍由 Popover 配置控制。`max.popover.content` 可覆盖浮层内容；`classNames` 对象/函数、styles、容器、触发方式和开关回调继续转发，`rootClassName` 是浮层配置类名。默认关闭销毁隐藏内容，可用 `destroyOnHidden:false` 保留内容状态。

组根原生 class/style/attrs 落在 div；两组件只暴露 `nativeElement`（span/div，可空）。没有头像业务 v-model 或额外实例方法。

## Component Token

通过 `ConfigProvider :theme="{components:{Avatar:{…}}}"` 设置当前组件 Token，支持源替换与移除、嵌套 Provider 和四种算法。每个实例与溢出内容读取所属主题；本地 style CSS 变量可覆盖对应根。

| Token | 类型 | 默认来源 |
|---|---|---|
| containerSize / containerSizeLG / containerSizeSM | `number` | controlHeight / controlHeightLG / controlHeightSM |
| textFontSize / textFontSizeLG / textFontSizeSM | `number` | fontSize |
| iconFontSize / iconFontSizeSM | `number` | 平均字号 / fontSize |
| iconFontSizeLG | `number \| string` | fontSizeHeading3 |
| groupSpace | `number` | marginXXS |
| groupOverlapping | `number`，允许负数 | -marginXS |
| groupBorderColor | `string` | colorBorderBg |

开发版事件与 Group 旧别名的直接迁移见 [Avatar 迁移说明](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/avatar-contracts.md)。


## 基本 (basic)

五种尺寸与圆形/方形；图标使用完整VNode数据。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo。

import { UserOutlined } from '@apollo-design/icons';
import { Avatar, Space } from '@apollo-design/ui';
import { h } from 'vue';

// 本地图标随库发布，不依赖外链资源。
const icon = () => h(UserOutlined);
</script>

<template>
  <Space vertical :size="16">
    <Space wrap :size="16">
      <Avatar :size="64" :icon="icon()" />
      <Avatar size="large" :icon="icon()" />
      <Avatar :icon="icon()" />
      <Avatar size="small" :icon="icon()" />
      <Avatar :size="14" :icon="icon()" />
    </Space>
    <Space wrap :size="16">
      <Avatar shape="square" :size="64" :icon="icon()" />
      <Avatar shape="square" size="large" :icon="icon()" />
      <Avatar shape="square" :icon="icon()" />
      <Avatar shape="square" size="small" :icon="icon()" />
      <Avatar shape="square" :size="14" :icon="icon()" />
    </Space>
  </Space>
</template>
```

## 类型 (type)

图片、完整VNode、自定义颜色、字符与图标。自定义颜色成对指定前景和背景。

### type.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 type demo。⚠️ 图片用 **data URI**（外网图片会污染 L6 基线）

import { UserOutlined } from '@apollo-design/icons';
import { Avatar, Space } from '@apollo-design/ui';
import { h } from 'vue';

const url =
  'data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 width=%2280%22 height=%2280%22 viewBox=%220 0 80 80%22%3E%3Crect width=%2280%22 height=%2280%22 fill=%22%23dbeafe%22/%3E%3Ccircle cx=%2240%22 cy=%2228%22 r=%2214%22 fill=%22%231e40af%22/%3E%3Cpath d=%22M12 80a28 28 0 0 1 56 0%22 fill=%22%231e40af%22/%3E%3C/svg%3E';
const icon = () => h(UserOutlined);
</script>

<template>
  <Space :size="16" wrap>
    <Avatar :icon="icon()" />
    <Avatar>U</Avatar>
    <Avatar :size="40">USER</Avatar>
    <Avatar :src="url" alt="avatar" />
    <Avatar :src="h('img', { draggable: false, src: url, alt: 'avatar' })" />
    <Avatar :style="{ backgroundColor: '#fde3cf', color: '#873800' }">U</Avatar>
    <Avatar :style="{ backgroundColor: '#87d068' }" :icon="icon()" />
  </Space>
</template>
```

## 自动调整字符大小 (dynamic)

切换姓名、配色和gap，观察文字随当前尺寸重新拟合。

### dynamic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 dynamic demo。
import { Avatar, Button, Space } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const UserList = ['U', 'Lucy', 'Tom', 'Edward'];
const ColorList = ['#f56a00', '#7265e6', '#ffbf00', '#00a2ae'];
const GapList = [4, 3, 2, 1];

const index = ref(0);
const gapIndex = ref(0);

const user = computed(() => UserList[index.value]);
const color = computed(() => ColorList[index.value]);
const gap = computed(() => GapList[gapIndex.value]);

const changeUser = () => {
  index.value = (index.value + 1) % UserList.length;
};
const changeGap = () => {
  gapIndex.value = (gapIndex.value + 1) % GapList.length;
};
</script>

<template>
  <Space wrap>
    <Avatar :style="{ backgroundColor: color, color: index === 1 ? '#fff' : '#1f1f1f', verticalAlign: 'middle' }" size="large" :gap="gap">
      {{ user }}
    </Avatar>
    <Button
      size="small"
      :style="{ margin: '0 16px', verticalAlign: 'middle' }"
      @click="changeUser"
    >
      ChangeUser
    </Button>
    <Button size="small" :style="{ verticalAlign: 'middle' }" @click="changeGap">changeGap</Button>
  </Space>
</template>
```

## 带徽标的头像 (badge)

组合徽标与头像。

### badge.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 badge demo。

import { UserOutlined } from '@apollo-design/icons';
import { Avatar, Badge, Space } from '@apollo-design/ui';
import { h } from 'vue';

const icon = () => h(UserOutlined);
</script>

<template>
  <Space :size="24">
    <Badge :count="1">
      <Avatar shape="square" :icon="icon()" />
    </Badge>
    <Badge dot>
      <Avatar shape="square" :icon="icon()" />
    </Badge>
  </Space>
</template>
```

## 头像组合 (group)

组合直接头像、链接和Tooltip；max.count只计算可见子项，额外显示溢出按钮。

### group.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 group demo。⚠️ 图片用 **data URI**（外网图片会污染 L6 基线）

import { UserOutlined } from '@apollo-design/icons';
import { Avatar, AvatarGroup, Divider, Tooltip } from '@apollo-design/ui';
import { h } from 'vue';

const url =
  'data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 width=%2280%22 height=%2280%22 viewBox=%220 0 80 80%22%3E%3Crect width=%2280%22 height=%2280%22 fill=%22%23dbeafe%22/%3E%3Ccircle cx=%2240%22 cy=%2228%22 r=%2214%22 fill=%22%231e40af%22/%3E%3Cpath d=%22M12 80a28 28 0 0 1 56 0%22 fill=%22%231e40af%22/%3E%3C/svg%3E';
const icon = () => h(UserOutlined);
const maxStyle = { color: '#873800', backgroundColor: '#fde3cf' };
</script>

<template>
  <AvatarGroup>
    <Avatar :src="url" alt="a" />
    <a href="#avatar-profile">
      <Avatar :style="{ backgroundColor: '#f56a00', color: '#1f1f1f' }">K</Avatar>
    </a>
    <Tooltip title="Apollo user" placement="top">
      <Avatar :style="{ backgroundColor: '#87d068' }" :icon="icon()" />
    </Tooltip>
    <Avatar :style="{ backgroundColor: '#1677ff' }" :icon="icon()" />
  </AvatarGroup>
  <Divider />
  <AvatarGroup :max="{ count: 2, style: maxStyle }">
    <Avatar :src="url" alt="a" />
    <Avatar :style="{ backgroundColor: '#f56a00', color: '#1f1f1f' }">K</Avatar>
    <Avatar :style="{ backgroundColor: '#87d068' }" :icon="icon()" />
    <Avatar :style="{ backgroundColor: '#1677ff' }" :icon="icon()" />
  </AvatarGroup>
  <Divider />
  <AvatarGroup size="large" :max="{ count: 2, style: maxStyle }">
    <Avatar :src="url" alt="a" />
    <Avatar :style="{ backgroundColor: '#f56a00', color: '#1f1f1f' }">K</Avatar>
    <Avatar :style="{ backgroundColor: '#87d068' }" :icon="icon()" />
    <Avatar :style="{ backgroundColor: '#1677ff' }" :icon="icon()" />
  </AvatarGroup>
  <Divider />
  <AvatarGroup shape="square">
    <Avatar :style="{ backgroundColor: '#fde3cf', color: '#873800' }">A</Avatar>
    <Avatar :style="{ backgroundColor: '#f56a00', color: '#1f1f1f' }">K</Avatar>
    <Avatar :style="{ backgroundColor: '#87d068' }" :icon="icon()" />
    <Avatar :style="{ backgroundColor: '#1677ff' }" :icon="icon()" />
  </AvatarGroup>
</template>
```

## maxCount 包含溢出元素 (max-count)

直接v-for渲染头像。开关只改变演示中预留的可见名额：两项加指示器，或三项加指示器；不改变max.count定义。

### max-count.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 max-count demo（「maxCount 包含溢出元素」）。
import { Avatar, AvatarGroup, Flex, InputNumber, Switch } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const avatarCount = ref(4);
const overflowInFinal = ref(true);

const mergedMaxCount = computed(() => (overflowInFinal.value ? 2 : 3));
</script>

<template>
  <Flex vertical gap="middle">
    <Flex :gap="24">
      <span>Avatar count: </span>
      <InputNumber
        :style="{ width: '120px' }"
        :min="2"
        :max="10"
        :value="avatarCount"
        aria-label="Avatar count"
        @update:value="(v) => typeof v === 'number' && (avatarCount = v)"
      />
    </Flex>
    <Flex :gap="8">
      <span>overflowInFinal: </span>
      <Switch :checked="overflowInFinal" aria-label="overflowInFinal" @update:checked="(v) => (overflowInFinal = v)" />

      <AvatarGroup
        :max="{ count: mergedMaxCount, style: { backgroundColor: '#52c41a', color: '#1f1f1f' } }"
      >
        <Avatar v-for="i in avatarCount" :key="i" style="background: #f56a00; color: #1f1f1f">{{ String.fromCharCode(64 + i) }}</Avatar>
      </AvatarGroup>
    </Flex>
  </Flex>
</template>
```

## 图片不存在时 (fallback)

本地无效图片数据触发真实error，回退到默认字符。自定义图片VNode自行管理其加载错误。

### fallback.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 fallback demo。
import { Avatar, Space } from '@apollo-design/ui';

// Invalid local image data exercises the real image error without a network request.
const broken = 'data:image/png,invalid';
</script>

<template>
  <Space>
    <Avatar shape="circle" :src="broken">A</Avatar>
    <Avatar shape="circle" :src="broken">ABC</Avatar>
  </Space>
</template>
```

## 隐藏情况下计算字符对齐 (toggle-debug)

切换隐藏状态、头像尺寸和外层视觉缩放，验证恢复显示后的文字测量。

### toggle-debug.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 toggle-debug demo（隐藏情况下计算字符对齐）。
import { Avatar, Button, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const hide = ref(true);
const sizes = ['small', 'medium', 'large'] as const;
const sizeIndex = ref(2);
const scale = ref(1);

const size = () => sizes[sizeIndex.value];

const toggle = () => {
  hide.value = !hide.value;
};
const toggleSize = () => {
  sizeIndex.value = (sizeIndex.value + 1) % sizes.length;
};
const changeScale = () => {
  scale.value = scale.value === 1 ? 2 : 1;
};
const hidden = () => ({ display: hide.value ? 'none' : '' });
</script>

<template>
  <Space wrap>
    <Button @click="toggle">Toggle Avatar visibility</Button>
    <Button @click="toggleSize">Toggle Avatar size</Button>
    <Button @click="changeScale">Change Avatar scale</Button>
  </Space>
  <div :style="{ textAlign: 'center', transform: `scale(${scale})`, marginTop: '24px' }">
    <Avatar :size="size()" :style="{ ...hidden(), background: '#7265e6', color: '#fff' }">Avatar</Avatar>
    <Avatar :size="size()" src="data:image/png,invalid" :style="{ ...hidden(), background: '#00a2ae', color: '#1f1f1f' }">
      Invalid
    </Avatar>
    <div :style="hidden()">
      <Avatar :size="size()" :style="{ background: '#7265e6', color: '#fff' }">Avatar</Avatar>
      <Avatar :size="size()" src="data:image/png,invalid" :style="{ background: '#00a2ae', color: '#1f1f1f' }">Invalid</Avatar>
    </div>
  </div>
</template>
```

## 响应式尺寸 (responsive)

根据当前匹配且已配置的最大断点调整尺寸；显示文字以便观察。

### responsive.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 responsive demo。
import { Avatar } from '@apollo-design/ui';

const responsiveSize = { xs: 24, sm: 32, md: 40, lg: 64, xl: 80, xxl: 100 };
</script>

<template>
  <Avatar :size="responsiveSize">Vue</Avatar>
</template>
```

## 当前组件 Token (component-token)

通过当前 ConfigProvider 修改十二个已有 Avatar Token。开关移除覆盖，溢出按钮可用鼠标或 Enter/Space 打开，观察隐藏头像间距。

### component-token.vue

```vue
<script setup lang="ts">
import { UserOutlined } from '@apollo-design/icons';
import { Avatar, AvatarGroup, ConfigProvider, Space, Switch } from '@apollo-design/ui';
import { ref } from 'vue';

const custom = ref(true);
const tokens = {
  containerSize: 48,
  containerSizeLG: 64,
  containerSizeSM: 36,
  textFontSize: 16,
  textFontSizeLG: 18,
  textFontSizeSM: 14,
  iconFontSize: 24,
  iconFontSizeLG: 32,
  iconFontSizeSM: 20,
  groupSpace: 10,
  groupOverlapping: -12,
  groupBorderColor: '#6250cc',
};
</script>
<template>
  <Space vertical :size="16">
    <label>Use custom Avatar tokens <Switch v-model:checked="custom" aria-label="Use custom Avatar tokens" /></label>
    <ConfigProvider :theme="custom ? {components:{Avatar:tokens}} : undefined">
      <Space :size="16" wrap>
        <Avatar size="small">S</Avatar><Avatar>M</Avatar><Avatar size="large">L</Avatar>
        <Avatar><template #icon><UserOutlined /></template></Avatar>
        <AvatarGroup :max="{count:2,popover:{trigger:'click'}}"><Avatar>A</Avatar><Avatar>B</Avatar><Avatar>C</Avatar><Avatar>D</Avatar></AvatarGroup>
      </Space>
    </ConfigProvider>
  </Space>
</template>
```

---

# BackTop

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/back-top


返回页面顶部的操作按钮。

> ⚠️ 该组件在 antd 6.x 已废弃，请使用 `FloatButton.BackTop`。本实现为兼容保留。

## 何时使用

- 当页面内容区域较长时，提供一个快速返回顶部的入口。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/back-top/demo)（deprecated 组件在 antd 仅剩 basic）。

## API

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| visibilityHeight | 滚动超过该值才显示（px） | `number` | `400` |
| duration | 回顶动画时长（ms；<=0 直落） | `number` | `450` |
| target | 滚动容器 getter；可返回尚未挂载的模板 ref，引用变化时自动重绑 | `() => HTMLElement \| Window \| Document \| null` | `ownerDocument` |
| prefixCls | 组件类名前缀 | `string` | `apollo-back-top` |

### 事件、插槽与实例

| 名称 | 契约 |
|---|---|
| `@click` | 回顶开始后触发一次，参数为原生 `MouseEvent`；支持 `.once` |
| 默认插槽 | 完整按钮内容，支持文本、数字、多节点和 Fragment；显式空槽隐藏按钮，未提供则显示默认图标 |
| `nativeElement` | 实例暴露的实际 `HTMLButtonElement \| null` |

根节点为 `type="button"` 的原生按钮，支持 Tab、Enter、Space 与焦点样式；不可见时不进入键盘顺序。
原生 `class` / `style`、`aria-*`、`data-*` 和原生监听器均落在按钮上。
默认图标使用名称“Back to top”；可用 `aria-label="返回顶部"` 本地化。自定义图标内容应提供可访问名称，不应嵌套按钮或链接。

`ConfigProvider.components['back-top']` 的 `className` / `style` 随配置替换和移除更新；根 `style` 优先。
`theme.components.BackTop.zIndexPopup` 控制层叠顺序，默认 `zIndexBase + 10`。主题 `motion: false` 或系统减少动态效果设置会关闭回顶动画。

## 设计说明

- `visibilityHeight={0}` 恒显。
- 默认内容为 `-content > -icon`（VerticalAlignTopOutlined），自定义内容完整渲染在稳定的 `-custom` 宿主中；动效类属于宿主，不修改插槽 VNode。
- 视口 ≤ 768px / ≤ 480px 时右边界收窄（响应式断点）。
- 更换容器、重复点击和卸载都会取消先前回顶动画；滚动监听及待执行帧在离开容器时释放。

## 开发期迁移（2026-10-30）

按 ADR 0007 直接修正旧 React DOM / 回调形态：根 `div` 改为原生按钮，默认 `div` 内容宿主改为 `span`，自定义内容增加稳定 `span` 宿主。依赖标签选择器或把按钮/链接放在默认槽内的调用方需调整；类名入口继续保留。
模板使用 `@click="handleClick"`；`h(BackTop, { onClick })` 仍以 `MouseEvent` 接收同一个事件。原来的首节点克隆改为完整默认槽消费，不需要手工包成单根。
此开发版修正无兼容层或弃用期，历史 DOM 基线保留，当前精确差异由本目录测试断言。


## 基本 (basic)

向下滚动内容区域，按钮在超过 100px 后显示。`target` 使用可跟踪模板 ref 的 getter，`@click` 接收原生点击事件。按钮定位在示例容器内，并显示回顶次数。（已废弃，请使用 FloatButton.BackTop）

### basic.vue

```vue
<script setup lang="ts">
import { BackTop } from '@apollo-design/ui';
import { ref } from 'vue';

const scrollTarget = ref<HTMLElement | null>(null);
const clicks = ref(0);
const getTarget = () => scrollTarget.value;

const lines = Array.from(
  { length: 20 },
  (_, index) => `第 ${index + 1} 行内容，向下滚动查看右下角按钮。`,
);
</script>

<template>
  <div style="position: relative">
    <div ref="scrollTarget" class="demo-back-top-content" style="height: 180px; overflow: auto" tabindex="0" aria-label="滚动内容">
      <p v-for="line in lines" :key="line">{{ line }}</p>
    </div>
    <BackTop
      :target="getTarget"
      :visibility-height="100"
      aria-label="返回顶部"
      style="position: absolute; inset-inline-end: 16px; inset-block-end: 16px"
      @click="clicks += 1"
    />
  </div>
  <p aria-live="polite">已返回顶部 {{ clicks }} 次。向下滚动内容区域以显示按钮。</p>
</template>
```

---

# Badge

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/badge


图标右上角的圆形徽标数字。

## 何时使用

- 一般出现在通知图标或头像的右上角位置，提示用户有消息或者有需要处理的项。
- 不强求数字一定要有确切的数值，也可以是文字或小红点。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/badge/demo)（13 个，包含数字计数与模板富内容场景）。

| demo | 内容 |
|---|---|
| `basic` | 基本（count / showZero / 无 count） |
| `no-wrapper` | 独立使用 |
| `overflow` | 封顶数字 |
| `dot` | 讨嫌的小红点 |
| `change` | 动态（数字滚动） |
| `link` | 可点击 |
| `offset` | 位移 |
| `size` | 大小 |
| `status` | 状态点 |
| `colorful` | 多彩徽标（13 预设色） |
| `ribbon` | 缎带（Badge.Ribbon） |
| `style-class` | 自定义语义结构的样式和类 |
| `content-slots` | 可切换富内容、空插槽、数字计数与圆点 |

## API

### Badge

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | DOM 类名前缀；任意前缀的 CSS 由调用方提供 | `string` | `apollo-badge` |
| scrollNumberPrefixCls | 数字轨道类名前缀 | `string` | `apollo-scroll-number` |
| count | 展示的数字（`null` 不显示；超出封顶显示 `+`） | `VNodeChild` | `null` |
| overflowCount | 封顶值 | `number` | `99` |
| dot | 只显示小红点，覆盖 count（含零值） | `boolean` | `false` |
| showZero | 数值为 0 时是否显示 | `boolean` | `false` |
| size | 尺寸（`default` 已废弃，等价 `medium`） | `'medium' \| 'small'` | `'medium'` |
| status | 状态点 | `'success' \| 'processing' \| 'error' \| 'default' \| 'warning'` | — |
| color | 自定义颜色（13 预设键走类名，其它色串走内联） | `string` | — |
| text | 状态文本 | `VNodeChild` | — |
| title | 指示器原生 title，含独立状态点；`null`/`false` 禁用，不传回落标量 count | `string \| null \| false` | — |
| offset | 偏移 `[x, y]`：x → `inset-inline-end`，y → `margin-top` | `[number \| string, number \| string]` | — |
| classNames / styles | 语义槽位（root / indicator） | — | — |

Vue 原生 `class` / `style`（对象、字符串、数组）、id、ARIA、tabindex 和监听器落根 span；指示器样式用 `styles.indicator`。Badge 不声明业务 emits 或 v-model；原生事件只触发一次。状态与计数共用根，父级更新保留业务内容、草稿和所属焦点。

非标量 count（VNode、数组、Fragment、多根组件、文本节点）与 #count 共用原生指示器和完整内容路径，不克隆业务节点。语义类/样式、title、offset 作用于指示器，子节点保留自身属性与身份。Vue 空内容不产生空徽标，独立 text 不依赖 count 可见性；条件组件为空时隐藏空宿主，保留业务实例。

### Badge 插槽

| 插槽 | 说明 |
| --- | --- |
| default | 被徽标包裹的内容 |
| count | 静态富内容指示器；覆盖 count prop，不进行封顶或数字位滚动 |
| text | 富文本状态文案；覆盖 text prop |

插槽按存在性优先，空结果隐藏对应内容；条件插槽移除后恢复 prop。`#count` 中的文本 `0` 按静态内容展示，`showZero` 和 `overflowCount` 控制数字 prop 分支；`dot` 仍优先于两种计数内容。富内容保留 indicator 样式、offset 与离场缓存，未显式设置 title 时不从 VNode 生成标题。数字滚动继续使用 count prop。

### Badge.Ribbon

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | DOM 类名前缀 | `string` | `apollo-ribbon` |
| className | 丝带本体的独立类；根类使用 Vue class | `string` | — |
| text | 丝带文本 | `VNodeChild` | — |
| color | 颜色 | `string` | — |
| placement | 挂靠角 | `'start' \| 'end'` | `'end'` |
| classNames / styles | 语义槽位（root / indicator / content） | — | — |

Ribbon 的 default 是被包裹内容，`#text` 是完整丝带内容。text 支持所有 VNodeChild，含数组、Fragment 和 0；插槽存在则优先，空槽不回退，条件槽移除后恢复 prop。原生 class/style 和其他 attrs 落 wrapper，丝带样式用 styles.indicator，文字样式用 styles.content。

### Expose 与当前配置

BadgeRef / RibbonRef 只读 `nativeElement: HTMLElement | null` 指向当前实际根，卸载后为空。ConfigProvider.components.badge / ribbon 的配置、方向和前缀保持响应性；语义对象或函数替换、移除立即生效。配置字段 style 保留独立目标：Badge 状态独立模式为 root、其他为 indicator；Ribbon 为 indicator。它与组件原生 style attrs 不同，明确区域推荐 styles。

## Theme

### Component Token（9 个）

| Token | 默认值 | 说明 |
|---|---|---|
| indicatorZIndex | `auto` | 指示器 z-index |
| indicatorHeight | `20px` | count 高度 |
| indicatorHeightSM | `14px` | 小尺寸高度 |
| dotSize | `6px` | 小红点尺寸 |
| textFontSize | `12px` | 计数字号 |
| textFontSizeSM | `12px` | 小尺寸计数字号 |
| textFontWeight | `normal` | 计数字重 |
| statusSize | `6px` | 状态点尺寸 |
| paddingInline | `8px` | 多字符内边距 |

九值由当前 Alias 派生，`theme.components.Badge` 可覆盖；适用 0、配置替换和移除均生效，显式根 CSS 变量优先。size/数字轨道使用相同实际高度。系统 reduced-motion 下停用波纹、滚动和出入场动画。

普通实色 count / Ribbon 使用可读前景，不改变原预设背景；显式 indicator/content color 优先。覆盖渐变、透明背景或完整样式时由作者配对前景。数字动画的额外轨道不参与朗读；组件不自动创建 live region。offset 的数字/数字字符串按 px，带单位、百分比或表达式保留为 CSS 长度。

开发期根 style / 内容 / 数字和引用修正见 [迁移说明](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/badge-contracts.md)。原始参考证据保留，不作为 Apollo 公共用法的判据。


## 基本 (basic)

简单的徽标展示，当 `count` 为 `0` 时默认不显示，但是可以使用 `showZero` 修改为显示。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo（Avatar/Icon 用原生元素等价替换，缺口见 README §7）
import { Badge, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Badge :count="5">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
    <Badge :count="0" :show-zero="true">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
    <Badge>
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
  </Space>
</template>
```

## 独立使用 (no-wrapper)

不包裹任何元素即是独立使用，可自定样式展示。

### no-wrapper.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 no-wrapper demo（独立使用）
import { Badge, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Badge :count="25" />
    <Badge
      :count="4"
      :styles="{ indicator: { backgroundColor: 'var(--apollo-color-bg-container)', color: 'var(--apollo-color-text-secondary)', boxShadow: '0 0 0 1px #d9d9d9 inset' } }"
    />
    <Badge class="demo-cls" :styles="{ indicator: { backgroundColor: '#52c41a' } }" :count="54" />
  </Space>
</template>
```

## 封顶数字 (overflow)

`overflowCount` 封顶数字，超过显示 `+`。

### overflow.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 overflow demo
import { Badge, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Badge :count="99">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
    <Badge :count="100" :overflow-count="10">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
    <Badge :count="1000" :overflow-count="999">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
  </Space>
</template>
```

## 讨嫌的小红点 (dot)

没有具体的数字。`dot` 优先级高于 `count`。

### dot.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 dot demo

import { Badge, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const count = ref(5);
</script>

<template>
  <Space wrap>
    <Badge :dot="true">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center">dot</div>
    </Badge>
    <Badge :dot="true" :count="count">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center">count</div>
    </Badge>
  </Space>
</template>
```

## 动态 (change)

展示动态计数、负号及数字滚动。动画轨道中的额外数字不参与朗读，系统 reduced-motion 下停止滚动过渡。

### change.vue

```vue
<script setup lang="ts">
// 使用本库操作按钮观察徽标数值更新。

import { Badge, Button, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const count = ref(5);
</script>

<template>
  <Space wrap :size="16">
    <Badge :count="count">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
    <Button :disabled="count === 0" aria-label="减少计数 / Decrease count" @click="count = Math.max(count - 1, 0)">-</Button>
    <Button aria-label="增加计数 / Increase count" @click="count = count + 1">+</Button>
    <Button @click="count = -12">负数 / Negative</Button>
    <Button @click="count = 5">重置 / Reset</Button>
  </Space>
</template>
```

## 可点击 (link)

用 a 标签包裹即可获得链接语义。

### link.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 link demo（Badge 包裹可点击元素）
import { Badge } from '@apollo-design/ui';
</script>

<template>
  <a href="#">
    <Badge :count="5">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center">link</div>
    </Badge>
  </a>
</template>
```

## 位移 (offset)

设置偏移量，`[x, y]` 分别为水平（`inset-inline-end` 方向）与垂直偏移。

### offset.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 offset demo
import { Badge, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap :size="32">
    <Badge :count="5" :offset="[10, 10]">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
    <Badge :count="5" :offset="[-10, 10]">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
  </Space>
</template>
```

## 大小 (size)

`size="small"` 缩小徽标（`default` 为废弃用法，等价 `medium`）。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size demo
import { Badge, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Badge :count="5">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
    <Badge :count="5" size="small">
      <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
  </Space>
</template>
```

## 状态点 (status)

用于表示事态的状态，`processing` 会触发波纹动画。

### status.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 status demo
import { Badge, Input, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Badge status="success" text="Success" />
    <Badge status="error" text="Error" />
    <Badge status="default" text="Default" />
    <Badge status="processing" text="Processing" />
    <Badge status="warning" text="Warning" />
    <Badge status="success"><span style="display: inline-block; width: 40px; height: 40px; background: var(--apollo-color-fill-alter)">A</span></Badge>
    <Badge status="processing"><Input aria-label="Wrapped status draft" placeholder="Draft" style="width: 100px" /></Badge>
  </Space>
</template>
```

## 多彩徽标 (colorful)

预设 13 种颜色（也可传自定义色串）。

### colorful.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 colorful demo
import { Badge, Space } from '@apollo-design/ui';

const colors = [
  'pink',
  'red',
  'yellow',
  'orange',
  'cyan',
  'green',
  'blue',
  'purple',
  'geekblue',
  'magenta',
  'volcano',
  'gold',
  'lime',
] as const;
</script>

<template>
  <Space wrap :size="[16, 12]">
  <Badge v-for="c in colors" :key="c" :color="c" :text="c" />
  </Space>
</template>
```

## 缎带 (ribbon)

缎带徽标（`Badge.Ribbon`），支持预设色与自定义色、`start` / `end` 两个挂角。

### ribbon.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 ribbon demo（Card 用原生 div 等价替换）
import { Badge } from '@apollo-design/ui';
</script>

<template>
  <div style="position: relative; padding: 24px; background: var(--apollo-color-bg-container); border-radius: 4px; width: calc(100% - 8px)">
    <Badge.Ribbon text="Hippopotamus">
      <div style="height: 60px; background: var(--apollo-color-fill-alter); border-radius: 4px" />
    </Badge.Ribbon>
    <Badge.Ribbon text="Hippopotamus" color="pink">
      <div style="height: 60px; background: var(--apollo-color-fill-alter); border-radius: 4px; margin-top: 16px" />
    </Badge.Ribbon>
    <Badge.Ribbon text="Hippopotamus" color="red">
      <div style="height: 60px; background: var(--apollo-color-fill-alter); border-radius: 4px; margin-top: 16px" />
    </Badge.Ribbon>
    <Badge.Ribbon text="start" placement="start" color="blue">
      <div style="height: 60px; background: var(--apollo-color-fill-alter); border-radius: 4px; margin-top: 16px" />
    </Badge.Ribbon>
    <Badge.Ribbon text="#2db7f5" color="#2db7f5">
      <div style="height: 60px; background: var(--apollo-color-fill-alter); border-radius: 4px; margin-top: 16px" />
    </Badge.Ribbon>
  </div>
</template>
```

## 自定义语义结构的样式和类 (style-class)

通过 `classNames` / `styles` 定制语义结构（root / indicator）。按钮切换九个已有 Token、适用零值与默认恢复；方向改变时输入草稿保留。Vue 原生 class/style 控制根，指示器样式使用 styles.indicator。

### style-class.vue

```vue
<script setup lang="ts">
import {
  Badge,
  Button,
  ConfigProvider,
  type ConfigProviderThemeConfig,
  Flex,
  Input,
  Ribbon,
} from '@apollo-design/ui';
import { computed, ref } from 'vue';

const stage = ref(0);
const rtl = ref(false);
const theme = computed<ConfigProviderThemeConfig>(() => {
  const components: NonNullable<ConfigProviderThemeConfig['components']> = {};
  if (stage.value === 1)
    components.Badge = {
      indicatorZIndex: 3,
      indicatorHeight: 28,
      indicatorHeightSM: 18,
      dotSize: 10,
      textFontSize: 15,
      textFontSizeSM: 11,
      textFontWeight: 700,
      statusSize: 10,
      paddingInline: 12,
    };
  else if (stage.value === 2)
    components.Badge = {
      indicatorZIndex: 0,
      indicatorHeight: 0,
      indicatorHeightSM: 0,
      dotSize: 0,
      textFontSize: 0,
      textFontSizeSM: 0,
      textFontWeight: 'normal',
      statusSize: 0,
      paddingInline: 0,
    };
  return { components };
});
</script>

<template>
  <Flex vertical gap="middle">
    <Badge
    :count="5"
    :class-names="{ indicator: 'demo-indicator-cls' }"
    :styles="{ indicator: { backgroundColor: '#52c41a', borderColor: 'transparent', boxShadow: 'none' } }"
  >
    <div style="width: 40px; height: 40px; background: var(--apollo-color-fill-alter); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center" />
    </Badge>
    <Flex gap="small" wrap>
      <Button @click="stage = 1">九个 Token / Nine tokens</Button>
      <Button @click="stage = 2">零值 / Zero</Button>
      <Button @click="stage = 0">恢复默认 / Reset</Button>
      <Button @click="rtl = !rtl">RTL / LTR</Button>
    </Flex>
    <ConfigProvider :theme="theme" :direction="rtl ? 'rtl' : 'ltr'"
      :components="{ badge: { classNames: () => ({ root: `demo-stage-${stage}` }) } }">
      <Flex gap="large" wrap style="padding-block: 12px">
        <Badge :count="15" :style="[{ marginInline: '8px' }, 'padding: 4px']" />
        <Badge :count="15" size="small" />
        <Badge dot />
        <Badge status="processing" text="Processing" />
        <Badge :count="5"><Input aria-label="Token and direction draft" placeholder="Draft" style="width: 100px" /></Badge>
        <Badge><template #count><strong>Rich padding</strong></template></Badge>
        <Badge dir="ltr" :count="5"><span>Native LTR</span></Badge>
        <Ribbon dir="ltr" text="Native LTR"><span>Root direction</span></Ribbon>
      </Flex>
    </ConfigProvider>
  </Flex>
</template>
```

## 模板内容与数字计数 (content-slots)

`#count` 展示静态富内容，不执行数字封顶或数字位滚动；需要数字滚动时使用 `count` prop。Badge 和 Ribbon 的 `#text` 支持完整富文本。插槽存在则覆盖内容 prop，空插槽隐藏对应内容；移除插槽后恢复 prop。`dot` 优先于计数内容（含零值），离场保留上一帧内容，两个输入节点保持。

### content-slots.vue

```vue
<script setup lang="ts">
import { Badge, Button, Flex, Input, Ribbon } from '@apollo-design/ui';
import { computed, Fragment, h, ref } from 'vue';

const custom = ref(true);
const empty = ref(false);
const dot = ref(false);
const count = ref(5);
const label = ref('New');
const dataCount = computed(() =>
  empty.value ? null : h(Fragment, [h('strong', label.value), h('em', ' Data'), 0]),
);
</script>

<template>
  <Flex vertical gap="middle">
    <Flex wrap gap="small">
      <Button @click="custom = !custom">切换插槽 / Toggle content</Button>
      <Button @click="empty = !empty">切换空内容 / Toggle empty</Button>
      <Button @click="label = 'Updated'">更新内容 / Update content</Button>
      <Button @click="dot = !dot">切换圆点 / Toggle dot</Button>
      <Button @click="count = count === 0 ? 100 : 0">数字 0 / 100</Button>
    </Flex>
    <div><Badge :count="count" :dot="dot" :offset="[6, 2]">
      <Input aria-label="Badge anchor state" placeholder="Inbox" style="width: 120px" />
      <template v-if="custom" #count><strong v-if="!empty">{{ label }}</strong><em v-if="!empty">!</em></template>
    </Badge></div>
    <div>VNode 数据 / VNode data: <Badge :count="dataCount" :styles="{ indicator: { paddingInline: '8px' } }" /></div>
    <Badge status="success" text="Prop status">
      <template v-if="custom" #text><strong v-if="!empty">{{ label }}</strong></template>
    </Badge>
    <Ribbon text="Prop ribbon" style="padding: 16px; max-width: 360px">
      <template v-if="custom" #text><strong v-if="!empty">{{ label }}</strong><em v-if="!empty">!</em></template>
      <Input aria-label="Ribbon anchor state" placeholder="Draft" style="width: 120px" />
    </Ribbon>
  </Flex>
</template>
```

---

# BorderBeam

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/border-beam


沿 HTML 容器边框流动的装饰性描边。

## API

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | Effect 的完整类名及运行时 CSS 变量前缀 | `string` | Provider 前缀 + `-border-beam` |
| color | 纯色或色标数组（0–100 映射到 0–70%，保留尾部淡出） | `string \| { color: string; percent: number }[]` | 主题主色渐变 |
| count | 有限且 ≥1 时向下取整，其余回落 1 | `number` | `1` |
| duration | 单圈秒数，有限且 >0 才生效，其余回落 6 | `number` | `6` |
| lineWidth | 流光厚度，数字补 px | `number \| string` | 主题 `lineWidth` |
| outset | 覆盖四边统一 inset；未传时分别跟随宿主边框宽度 | `number \| string` | — |
| size | 流光头部长度，数字补 px | `number \| string` | `100px` |
| classNames.effect | 每个装饰 Effect div 的类名 | `{ effect?: string }` | — |
| styles.effect | 每个装饰 Effect div 的内联样式 | `{ effect?: CSSProperties }` | — |

## 插槽与原生 attrs

默认插槽接受 `VNodeChild`。单一 HTML 根元素可以被装饰，包括组件条件渲染或异步解析后的单根。注释、空白以及单根 Fragment 保留宿主；文本、SVG 和多个有效根完整透传，不绘制流光，也不添加布局容器。

原生 `class`、`style`、`data-*`、`aria-*` 和事件按 Vue 规则合并到选中的宿主 VNode。同名样式由宿主自身优先；组件宿主仍遵守该组件的 attrs 传递规则。原有 key、模板 ref、ref 数组、具名插槽和生命周期钩子由原调用方保有。要访问宿主元素或组件，请在子节点上放模板 ref；BorderBeam 不提供公开方法、事件或 v-model。

宿主自行提供定位上下文，通常设置 `position: relative`。Effect 继承圆角、不接收指针事件，并标记 `aria-hidden`。Effect 样式依次合并运行时变量、Provider `style`、Provider `styles.effect`、组件 `styles.effect`，后者优先。Provider 的 `className` 和 `classNames.effect` 仍是 Effect 配置。

可见宿主的边框宽度使用同一个 500ms 共享时钟采样，并读取实际所属文档。隐藏文档不读样式，恢复可见后立即补采样。没有 HTML 宿主即无采样订阅；更换宿主、迁移文档和卸载会清理相关资源。SSR 只保留内容，不创建 Effect 或定时器。减少动态效果偏好下隐藏流光。

## 迁移

已删除组件的 `className` 和原先落在 Effect 的 `style` Props。宿主使用原生 `class`/`style`，装饰层使用 `classNames.effect`/`styles.effect`。Vue 更新宿主文本而移除装饰节点时，会重建装饰层，保留宿主身份与焦点。


## 基础用法 (basic)

包裹任意内容，展示沿边框流动的流光。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { BorderBeam } from '@apollo-design/ui';
</script>

<template>
  <BorderBeam >
    <div style="position: relative; border: 1px solid var(--apollo-color-border); border-radius: 8px; padding: 24px">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</div>
  </BorderBeam>
</template>
```

## 鼠标悬浮时显示 (hover)

通过状态控制流光的显示与隐藏。鼠标悬浮或键盘聚焦都可预览；装饰层透明度变化时保留同一宿主，避免切换 DOM 引起闪动。

Hover or focus the same host to preview the effect without remounting its content.

### hover.vue

```vue
<script setup lang="ts">
import { BorderBeam } from '@apollo-design/ui';
import { ref } from 'vue';

const active = ref(false);
</script>

<template>
  <BorderBeam :styles="{ effect: { opacity: active ? 1 : 0 } }">
    <div
      style="position: relative; border: 1px solid var(--apollo-color-border); border-radius: 8px; padding: 24px"
      tabindex="0"
      aria-label="Hover or focus to preview the border beam"
      @mouseenter="active = true"
      @mouseleave="active = false"
      @focus="active = true"
      @blur="active = false"
    >
      Hover or focus me
    </div>
  </BorderBeam>
</template>
```

## 多条流光 (count)

`count` 大于 1 时展示多条错相流动的流光。

### count.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 count demo
import { BorderBeam } from '@apollo-design/ui';
</script>

<template>
  <BorderBeam :count="3">
    <div style="position: relative; border: 1px solid var(--apollo-color-border); border-radius: 8px; padding: 24px">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</div>
  </BorderBeam>
</template>
```

## 自定义容器 (custom-container)

流光跟随宿主的圆角与边框（`border-radius: inherit`）。原生 `class/style` 修饰宿主，`styles.effect` 只修饰装饰层。

### custom-container.vue

```vue
<script setup lang="ts">
// 原生 class/style 修饰宿主；styles.effect 只修饰装饰层。
import { BorderBeam } from '@apollo-design/ui';
</script>

<template>
  <BorderBeam :size="40" class="custom-beam-host" :style="{ padding: '8px' }" :styles="{ effect: { opacity: 0.8 } }">
    <div
      style="position: relative; border-radius: 16px; height: 64px; display: flex; align-items: center; justify-content: center; border: 1px solid var(--apollo-color-border)"
    >
      Custom container
    </div>
  </BorderBeam>
</template>
```

## 渐变色 (customized-color)

`color` 传色标数组（0–100 会线性映射到 0–70% 保留尾部淡出）。

### customized-color.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 customized-color demo
import { BorderBeam } from '@apollo-design/ui';

const stops = [
  { color: '#722ed1', percent: 20 },
  { color: '#2db7f5', percent: 50 },
  { color: '#87d068', percent: 80 },
];
</script>

<template>
  <BorderBeam :color="stops">
    <div style="position: relative; border: 1px solid var(--apollo-color-border); border-radius: 8px; padding: 24px">Gradient</div>
  </BorderBeam>
</template>
```

## 动画时长 (duration)

`duration` 控制单圈时长（秒）。

### duration.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 duration demo
import { BorderBeam } from '@apollo-design/ui';
</script>

<template>
  <BorderBeam :duration="12">
    <div style="position: relative; border: 1px solid var(--apollo-color-border); border-radius: 8px; padding: 24px">Slower</div>
  </BorderBeam>
</template>
```

## 尺寸 (size)

`size` 控制流光头部长度。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size demo
import { BorderBeam } from '@apollo-design/ui';
</script>

<template>
  <BorderBeam :size="160">
    <div style="position: relative; border: 1px solid var(--apollo-color-border); border-radius: 8px; padding: 24px">Bigger beam</div>
  </BorderBeam>
</template>
```

## 线宽 (line-width)

`lineWidth` 控制流光描边厚度（默认随宿主 border 宽度）。

### line-width.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 line-width demo
import { BorderBeam } from '@apollo-design/ui';
</script>

<template>
  <BorderBeam :line-width="8">
    <div style="position: relative; border: 8px solid var(--apollo-color-border); border-radius: 8px; padding: 24px">Thick border</div>
  </BorderBeam>
</template>
```

---

# Breadcrumb

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/breadcrumb


显示当前页面在层级结构中的位置，提供向上导航。可以使用数据项，也可以在默认插槽中组合 `BreadcrumbItem` / `BreadcrumbSeparator`。

## 代码演示

`demo/` 包含基础导航、图标、参数、菜单、分隔符、原生子组件、作用域插槽、语义样式和主题变量等 11 个成对示例。`debug-routes` 仅演示旧 `routes` 数据的迁移。

## API

### Breadcrumb

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| items | 数据源；提供 `[]` 时保持空列表，不消费默认槽 | `BreadcrumbItemInput[]` | — |
| routes | 已废弃的旧数据通道，使用 `items` | `BreadcrumbItemInput[]` | — |
| params | 替换字符串 title/path 中完整的 `:key`；支持重复参数、0、空字符串，缺失或空值保留占位符 | `Record<string, unknown>` | `{}` |
| separator | 自动分隔符；插槽优先，否则 prop → 当前 Provider → 默认值 | `VNodeChild` | `/` |
| dropdownIcon | 菜单按钮的装饰图标；插槽优先，否则 prop → 当前 Provider → 默认值 | `VNodeChild` | `DownOutlined` |
| prefixCls | 根及所属 Item/Separator 的当前前缀；自定义前缀须自行提供对应静态 CSS | `string` | `apollo-breadcrumb` |
| classNames | `root` / `item` / `separator` 类名；函数读取当前解析 props | `BreadcrumbSemanticClassNames \| ((info: { props: BreadcrumbProps }) => BreadcrumbSemanticClassNames)` | — |
| styles | 相同语义区域的样式；函数读取当前解析 props | `BreadcrumbSemanticStyles \| ((info: { props: BreadcrumbProps }) => BreadcrumbSemanticStyles)` | — |

原生 `class`、`style`、`id`、ARIA/data attrs 和监听器落根 `<nav>`。原生 style 最后覆盖语义样式及主题变量。Provider 支持 `components.breadcrumb` 的 `className`、`style`、`classNames`、`styles`、`separator`、`dropdownIcon`，均读取当前值。根没有组件事件或 v-model；暴露 `nativeElement: HTMLElement | null`。

| 插槽 | 作用域 | 行为 |
| --- | --- | --- |
| default | — | 只在未提供 items/routes 时组合原生子组件；保留调用方 key |
| itemRender | `{ route, params, routes, paths, href }` | 替换该数据项的默认内容；paths/href 对应该项 |
| separator | — | 替换自动分隔符 |
| dropdownIcon | — | 替换菜单按钮中的装饰图标 |

插槽存在则优先，包括有意为空的槽；条件槽出现/移除会更新，移除后恢复内容 prop/默认值。最后一项不自动追加分隔符。自定义 itemRender 内容直接进入稳定内容宿主，调用者负责其链接、ARIA、事件和样式。

### 数据项

`BreadcrumbItemInput = Partial<BreadcrumbItemType & BreadcrumbSeparatorType>`。

| 字段 | 说明 | 类型 |
| --- | --- | --- |
| key | 业务身份；省略则使用索引，重排建议显式指定 | `string \| number` |
| title | 完整 Vue 内容；仅字符串做参数替换 | `VNodeChild` |
| href | 直接链接 | `string` |
| path | 当前片段与此前 path 累加为 `#/a/b`；提供时优先于 href | `string` |
| className / style | 默认链接/文本/操作按钮的类名与有效内联样式 | `string` / `CSSProperties` |
| onClick | 默认内容元素的原生点击；无 href 时使用原生 button | `(event: MouseEvent) => void` |
| `aria-*` / `data-*` | 默认内容元素的属性 | — |
| menu | 菜单项及 Menu 配置 | `BreadcrumbItemMenu` |
| dropdownProps | Dropdown 配置；受控开合使用 open/onOpenChange | `DropdownProps` |
| breadcrumbName / children | 旧 routes 通道转换的标题/一层菜单，已废弃 | `string` / `Omit<BreadcrumbItemType, 'children'>[]` |
| type / separator | `type: 'separator'` 表示独立装饰分隔符，不参与 path 累加 | `'separator'` / `VNodeChild` |

菜单项支持 `key`、`label` / `title`、`href`、`path` 和 Menu 的 `disabled`、图标、额外内容及业务事件字段。显式 `href` 优先；否则 `path` 连接当前项 href，无 base 时直接使用 path。label 显式存在（包括空值）时优先于 title。

### BreadcrumbItem / BreadcrumbSeparator

`BreadcrumbItem` 支持 `href`、`menu`、`dropdownProps`、`dropdownIcon`、`separator`、`prefixCls`，默认槽是完整内容，另有 `#separator`、`#dropdownIcon`。本地槽优先于本地 prop，再回落所属 Breadcrumb 当前值。原生 class/style、id、ARIA/data attrs 和监听器落所属 `<li>`；`@click` 接收一次原生 MouseEvent。最后一项的自动分隔符被抑制。

`BreadcrumbSeparator` 只有默认内容槽与原生 attrs，落装饰 `<li aria-hidden="true">`。未提供槽显示 `/`，存在的空槽保留空内容。其前缀与语义样式来自所属 Breadcrumb；组件不允许 attrs 取消装饰隐藏语义。两种子组件均受支持，无整组件弃用告警，无额外 expose 或模型。

### 菜单与键盘

导航链接和菜单按钮是兄弟节点。菜单按钮有独立可访问名称，支持鼠标、Enter、Space 及 ArrowDown 打开；键盘打开后焦点进入菜单，菜单使用自身方向键行为。Escape 请求关闭，实际接受关闭且焦点仍属菜单时返回按钮；受控拒绝或焦点已移到外部时保持当前焦点。默认触发为箭头按钮的 hover/click，可由 dropdownProps.trigger 调整，原生按钮仍保留键盘入口。

## Design Token

当前主题、暗色/紧凑算法、嵌套 Provider 和运行时替换均应用到根 CSS 变量；原生 style 可覆盖。

| Token | 默认来源 | 消费点 |
| --- | --- | --- |
| itemColor | `colorTextSecondary` | 普通文字 |
| lastItemColor | `colorText` | 末项文字 |
| linkColor | `colorTextSecondary` | 默认链接/操作按钮 |
| linkHoverColor | `colorText` | 链接与菜单区域 hover |
| iconFontSize | `fontSize` | 内容中的 Apollo 图标；下拉箭头使用 fontSizeIcon |
| separatorColor | `colorTextDescription` | 装饰分隔符 |
| separatorMargin | `marginXS` | 分隔符两侧间距 |

详见 [Breadcrumb 契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/breadcrumb-contracts.md)。


## 基本 (basic)

最简单的用法。`title` 可以是字符串，也可以是一个 vnode（链接、图标…）；
最后一项目标没有 `href` ⇒ 渲染成 `<span>`（不可点）。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo。
import { Breadcrumb, type BreadcrumbItemInput } from '@apollo-design/ui';
import { h } from 'vue';

const items: BreadcrumbItemInput[] = [
  { title: 'Home' },
  { title: h('a', { href: '' }, 'Application Center') },
  { title: h('a', { href: '' }, 'Application List') },
  { title: 'An Application' },
];
</script>

<template>
  <Breadcrumb :items="items" />
</template>
```

## 分隔符 (separator)

用 `separator` 覆盖默认的 `/`。

### separator.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 separator demo。
import { Breadcrumb, type BreadcrumbItemInput } from '@apollo-design/ui';

const items: BreadcrumbItemInput[] = [
  { title: 'Home' },
  { title: 'Application Center', href: '' },
  { title: 'Application List', href: '' },
  { title: 'An Application' },
];
</script>

<template>
  <Breadcrumb separator=">" :items="items" />
</template>
```

## 独立分隔符 (separator-component)

用 `type: 'separator'` 的项插入**独立**分隔符（可以与默认分隔符并存）。
把 `separator` 设为 `''` 可以去掉自动分隔符。

### separator-component.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 separator-component demo。
import { Breadcrumb, type BreadcrumbItemInput } from '@apollo-design/ui';

const items: BreadcrumbItemInput[] = [
  { title: 'Location' },
  { type: 'separator', separator: ':' },
  { href: '', title: 'Application Center' },
  { type: 'separator' },
  { href: '', title: 'Application List' },
  { type: 'separator' },
  { title: 'An Application' },
];
</script>

<template>
  <Breadcrumb separator="" :items="items" />
</template>
```

## 带图标 (with-icon)

`title` 里可以放图标。第三种是**第三方图标**（裸 `<svg>`，没有 `.apollo-icon` 包裹）
—— 它靠 `.{p}-link > svg` 那条规则居中、并与文字保持间距。

### with-icon.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 withIcon demo。
import { HomeOutlined, UserOutlined } from '@apollo-design/icons';
import { Breadcrumb, type BreadcrumbItemInput } from '@apollo-design/ui';
import { h } from 'vue';

// 第三方图标：直接渲染裸 `<svg>`（没有 `.apollo-icon` 包裹）。
const ChartIcon = () =>
  h(
    'svg',
    {
      viewBox: '0 0 24 24',
      width: '1em',
      height: '1em',
      fill: 'none',
      stroke: 'currentColor',
      'stroke-width': 2,
      'aria-hidden': 'true',
    },
    [h('path', { d: 'M3 3v18h18' }), h('path', { d: 'M7 14l4-4 3 3 5-6' })],
  );

const items: BreadcrumbItemInput[] = [
  { href: '', title: h(HomeOutlined), 'aria-label': 'Home' },
  { href: '', title: [h(UserOutlined), h('span', null, 'Application List')] },
  { href: '', title: [h(ChartIcon), h('span', null, 'Dashboard')] },
  { title: 'Application' },
];
</script>

<template>
  <Breadcrumb :items="items" />
</template>
```

## 路径参数 (with-params)

`params` 会把 `title`（以及 `path`）里的 `:key` 替换成实际值。

### with-params.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 withParams demo。
import { Breadcrumb, type BreadcrumbItemInput } from '@apollo-design/ui';

const items: BreadcrumbItemInput[] = [{ title: 'Users' }, { title: ':id', href: '' }];
</script>

<template>
  <Breadcrumb :items="items" :params="{ id: 1 }" />
</template>
```

## 带下拉菜单 (overlay)

项的 `menu` 会让它带一个下拉菜单（外层是 `.{p}-overlay-link`，并渲染 `dropdownIcon`）。

### overlay.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 overlay demo。
import { Breadcrumb, type BreadcrumbItemInput } from '@apollo-design/ui';
import { h } from 'vue';

const menuItems = [
  {
    key: '1',
    label: h(
      'a',
      { target: '_blank', rel: 'noopener noreferrer', href: 'http://www.alipay.com/' },
      'General',
    ),
  },
  {
    key: '2',
    label: h(
      'a',
      { target: '_blank', rel: 'noopener noreferrer', href: 'http://www.taobao.com/' },
      'Layout',
    ),
  },
  {
    key: '3',
    label: h(
      'a',
      { target: '_blank', rel: 'noopener noreferrer', href: 'http://www.tmall.com/' },
      'Navigation',
    ),
  },
];

const items: BreadcrumbItemInput[] = [
  { title: 'Ant Design' },
  { title: h('a', { href: '' }, 'Component') },
  { title: h('a', { href: '' }, 'General'), menu: { items: menuItems } },
  { title: 'Button' },
];
</script>

<template>
  <Breadcrumb :items="items" />
</template>
```

## 废弃的 routes (debug-routes)

⚠️ `routes` **已废弃**（用 `items`）。`breadcrumbName` 会被映射成 `title`，
`children` 会被折成 `menu.items`；每一层 `path` 会**累加**成 `href`。

### debug-routes.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 debug-routes demo。
// ⚠️ `routes` 已废弃 —— 这里只为展示「老代码迁移过来会长什么样」。
import { Breadcrumb, type BreadcrumbItemInput } from '@apollo-design/ui';

const routes: BreadcrumbItemInput[] = [
  { path: '/home', breadcrumbName: 'Home' },
  {
    path: '/user',
    breadcrumbName: 'User',
    children: [
      { path: '/user1', breadcrumbName: 'User1' },
      { path: '/user2', breadcrumbName: 'User2' },
    ],
  },
];
</script>

<template>
  <Breadcrumb :routes="routes" />
</template>
```

## 原生组合与当前内容槽 (native)

原生 attrs 落所属 Item 的 li；导航与菜单按钮独立。使用条件插槽更换图标/分隔符，通过 dropdownProps.open/onOpenChange 控制菜单。

Native attrs belong to the Item li. Navigation and menu buttons are independent. Conditional slots change icons/separators; dropdownProps.open/onOpenChange controls the menu.

### native.vue

```vue
<script setup lang="ts">
import { Breadcrumb, BreadcrumbItem, BreadcrumbSeparator, Button } from '@apollo-design/ui';
import { ref } from 'vue';

const menuOpen = ref(false);
const custom = ref(true);
const menu = {
  items: [
    { key: 'guide', title: 'Guide', href: '#guide' },
    { key: 'api', title: 'API', href: '#api' },
    { key: 'future', title: 'Future guide', disabled: true },
  ],
};
</script>

<template>
  <Button style="margin-bottom: 12px" @click="custom = !custom">
    Toggle separator and icon slots
  </Button>
  <Breadcrumb aria-label="Documentation path">
    <template v-if="custom" #separator><span>›</span></template>
    <template v-if="custom" #dropdownIcon><span>⌄</span></template>
    <BreadcrumbItem href="#home" id="documentation-home" class="native-crumb">
      Home
    </BreadcrumbItem>
    <BreadcrumbItem
      :menu="menu" :dropdown-props="{
        open: menuOpen,
        onOpenChange: (open: boolean) => { menuOpen = open; },
      }"
    >
      <strong>Documentation</strong>
    </BreadcrumbItem>
    <BreadcrumbSeparator><span>·</span></BreadcrumbSeparator>
    <BreadcrumbItem aria-current="page">Breadcrumb</BreadcrumbItem>
  </Breadcrumb>
</template>
```

## 原生作用域与子组件 (scoped-item)

`#itemRender` 接收单个对象，包括当前路由、逐项路径与已解析的 href。可动态添加或移除插槽，空内容不回退。原生子组件按 Vue key 保留重排后的输入状态。

<!-- en-US -->

The item slot receives one named object with the current route, per-item paths and resolved href. Conditional and empty slots update normally. Native child composition preserves keyed input state during reorder.

### scoped-item.vue

```vue
<script setup lang="ts">
import { Breadcrumb, BreadcrumbItem, Button, Input } from '@apollo-design/ui';
import { ref } from 'vue';

const custom = ref(false);
const empty = ref(false);
const id = ref(42);
const order = ref(['a', 'b']);
const items = [
  { title: 'Apps', path: 'apps' },
  { title: 'Detail', path: ':id' },
];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 12px">
    <Button @click="custom = !custom">Toggle item slot</Button>
    <Button @click="empty = !empty">Toggle empty item</Button>
    <Button @click="id++">Update route params</Button>
    <Button @click="order = [...order].reverse()">Reorder native crumbs</Button>
  </div>
  <Breadcrumb :items="items" :params="{ id }" aria-label="Scoped breadcrumb">
    <template v-if="custom" #itemRender="{ route, paths, href }">
      <a v-if="!empty" :href="href" :data-route-path="paths.join('/')">{{ route.title }}</a>
    </template>
  </Breadcrumb>
  <Breadcrumb aria-label="Native breadcrumb" style="margin-top: 12px">
    <BreadcrumbItem v-for="key in order" :key="key">
      <span>{{ key }}</span>
      <Input :aria-label="`Crumb ${key}`" :placeholder="key" style="width: 80px" />
    </BreadcrumbItem>
  </Breadcrumb>
</template>
```

## 组件 Token (component-token)

通过根元素的 `--apollo-breadcrumb-*` 组件 Token 变量自定义链接颜色、悬浮颜色、末项颜色与分隔符间距。颜色引用当前主题的语义变量，随暗色与紧凑主题更新。

Override the root `--apollo-breadcrumb-*` variables to customize links, hover, the current item and separator spacing. Semantic color variables follow the current light, dark and compact theme.

### component-token.vue

```vue
<script setup lang="ts">
// 组件 Token：在根元素覆写 `--apollo-breadcrumb-*` 变量。
import type { BreadcrumbItemInput } from '@apollo-design/ui';
import { Breadcrumb } from '@apollo-design/ui';
import { h } from 'vue';

const items: BreadcrumbItemInput[] = [
  { title: h('a', { href: '' }, 'Home') },
  { title: h('a', { href: '' }, 'Application Center') },
  { title: 'Application List' },
];

const tokenStyle = {
  '--apollo-breadcrumb-link-color': 'var(--apollo-color-text-secondary)',
  '--apollo-breadcrumb-link-hover-color': 'var(--apollo-color-text)',
  '--apollo-breadcrumb-last-item-color': 'var(--apollo-color-text)',
  '--apollo-breadcrumb-separator-color': 'var(--apollo-color-text-secondary)',
  '--apollo-breadcrumb-separator-margin': '12px',
};
</script>

<template>
  <Breadcrumb :items="items" :style="tokenStyle" />
</template>
```

## 语义化样式 (style-class)

通过 `classNames` 与 `styles` 自定义面包屑的根节点、每一项与分隔符的样式。

链接在悬浮时会使用组件 Token 中的 `link-hover-color` 给出颜色反馈。

### style-class.vue

```vue
<script setup lang="ts">
// 语义化 classNames / styles：root / item / separator 三个槽位。
import type { BreadcrumbItemInput } from '@apollo-design/ui';
import { Breadcrumb } from '@apollo-design/ui';
import { h } from 'vue';

const items: BreadcrumbItemInput[] = [
  { title: h('a', { href: '' }, 'Home') },
  { title: h('a', { href: '' }, 'Components') },
  { title: 'Breadcrumb' },
];

const classNames = {
  root: 'demo-breadcrumb-root',
  item: 'demo-breadcrumb-item',
  separator: 'demo-breadcrumb-separator',
};

const styles = {
  root: {
    padding: '12px 16px',
    borderRadius: '8px',
    backgroundColor: 'var(--apollo-color-fill-quaternary)',
  },
  item: { fontWeight: 500 },
};
</script>

<template>
  <Breadcrumb :items="items" :class-names="classNames" :styles="styles" />
</template>

<style>
.demo-breadcrumb-root {
  border: 1px solid var(--apollo-color-border-secondary);
}

.demo-breadcrumb-separator {
  font-weight: 700;
}
</style>
```

---

# Button

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/button


按钮触发操作，或通过原生链接导航。

## 何时使用

用于提交表单、确认操作或触发当前页面中的动作。需要跳转时使用 `href`，由原生链接承载导航。

## 代码演示

保留全部 20 个原示例：`basic`, `block`, `chinese-chars-loading`, `chinese-space`, `color-variant`, `component-token`, `custom-disabled-bg`, `danger`, `disabled`, `ghost`, `href`, `icon`, `icon-placement`, `linear-gradient`, `loading`, `multiple`, `semantic`, `shape`, `size`, `style-class`.

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 视觉类型糖，显式 color/variant 可分别覆盖 | `ButtonType` | 'default' |
| color | 独立生效的语义色或预设色 | `ButtonColorType` | — |
| variant | 独立生效的视觉变体 | `ButtonVariantType` | — |
| icon | 图标数据或 Vue 组件；#icon 优先 | `ButtonIcon` | — |
| iconPosition | 已有废弃别名，使用 iconPlacement | `ButtonIconPlacement` | — |
| iconPlacement | 图标位置，覆盖已有别名 | `ButtonIconPlacement` | 'start' |
| shape | 形状；square 为方角 | `ButtonShape` | 'default' |
| size | 尺寸，依次取局部、Compact、Provider | `ButtonSize` | — |
| disabled | 禁用；显式 false 覆盖父级 true | `boolean` | — |
| loading | 请求立即阻止点击，delay 只推迟指示器 | `ButtonLoading` | false |
| prefixCls | 根类名前缀 | `string` | apollo-btn |
| ghost | 透明背景；solid 映射为 outlined | `boolean` | false |
| danger | 危险颜色糖，低于显式 color | `boolean` | false |
| block | 撑满容器 | `boolean` | false |
| href | 定义时渲染 a，空字符串也是有效链接值 | `string` | — |
| htmlType | button 根的原生 type | `ButtonHTMLType` | 'button' |
| autoInsertSpace | 两个中文字的视觉字距，保留连续原文 | `boolean` | true |
| classNames | root/icon/content 对象式类名 | `ButtonSemanticClassNames` | — |
| styles | root/icon/content 对象式样式 | `ButtonSemanticStyles` | — |

`ButtonType`: default / primary / dashed / link / text. `ButtonShape`: default / circle / round / square.
`ButtonSize`: small / medium / middle / large. `ButtonVariantType`: outlined / dashed / solid / filled / text / link.
`ButtonColorType`: default / primary / danger / blue / purple / cyan / green / magenta / pink / red / orange / yellow / volcano / geekblue / lime / gold.
`ButtonHTMLType`: button / submit / reset. `ButtonIconPlacement`: start / end.
`ButtonIcon = VNodeChild | Component`; `ButtonLoading = boolean | { delay?: number; icon?: ButtonIcon }`.

### 当前配置与原生属性

color、variant 各自先取显式值，再取 type/danger 糖，最后取当前 Provider；没有颜色时 solid 用 primary，其他变体用 default。显式 color 优先于 danger。ghost 把 solid 映射为 outlined。Provider 替换、删除、恢复均使用当前配置。

Vue class、字符串/对象/数组 style 和其他原生 attrs 落在真实 button/anchor 根；原生 style 优先于语义根样式和源 Token。表单属性、原生事件正常消费。启用链接尊重调用者 tabindex；禁用时移除 href 并强制 tabindex=-1。自定义前缀需配套静态 CSS，例如 genButtonStyle('my-app') 对应 .my-app-btn。

### 插槽

| 名称 | 内容 |
|---|---|
| default | 完整 Vue 内容；注释和空 Fragment 不产生空宿主 |
| icon | 完整 Vue 图标内容，优先于 icon 数据；有意空槽隐藏回退 |

组件拥有的 .apollo-btn-content 接收 content 类和样式。业务子 VNode、文字、状态和 ref 保持原样；中文字距由 CSS 实现，DOM 和可访问名保留连续原文。语义样式仅接受对象，不包含函数式 API。

### Emits 与 ref

click 发出一次原生 MouseEvent。disabled 或加载请求阻止激活、默认提交和事件传播，延迟显示期间也不触发 click。加载保留焦点，通过 aria-busy/aria-disabled 表达状态。有限正 delay 只延迟指示器；取消或卸载清理，单独替换图标不重计时，SSR 不创建计时器。内置加载图形为装饰；仅图标按钮应通过 aria-label 提供操作名称。

唯一 expose 是 nativeElement: HTMLButtonElement | HTMLAnchorElement | null，挂载前及卸载后为 null。没有 v-model 或其他 focus/blur 服务。

### 组件 Token 与导出

下列 45 个显式字段及 13 个已有预设阴影字段均消费当前 theme.components.Button。原生根变量（如 --apollo-btn-content-font-size）优先。数字长度转 px，字重/行高为无单位；有限非负尺寸保留 0，无效数字尺寸回退。移除源配置恢复继承/静态默认值。

| Token | 职责 |
|---|---|
| fontWeight | 字重 |
| iconGap | 图标与内容间距 |
| defaultShadow | 阴影 |
| primaryShadow | 阴影 |
| dangerShadow | 阴影 |
| primaryColor | 主色实心按钮三态文字色，默认 colorTextLightSolid（白色） |
| defaultColor | 对应颜色及状态的文字、背景或边框 |
| defaultBg | 对应颜色及状态的文字、背景或边框 |
| defaultBorderColor | 对应颜色及状态的文字、背景或边框 |
| dangerColor | 危险实心按钮三态文字色，默认 colorTextLightSolid（白色） |
| defaultHoverBg | 对应颜色及状态的文字、背景或边框 |
| defaultHoverColor | 对应颜色及状态的文字、背景或边框 |
| defaultHoverBorderColor | 对应颜色及状态的文字、背景或边框 |
| defaultActiveBg | 对应颜色及状态的文字、背景或边框 |
| defaultActiveColor | 对应颜色及状态的文字、背景或边框 |
| defaultActiveBorderColor | 对应颜色及状态的文字、背景或边框 |
| borderColorDisabled | 对应颜色及状态的文字、背景或边框 |
| defaultBorderColorDisabled | 对应颜色及状态的文字、背景或边框 |
| groupBorderColor | 组及 Compact 接缝 |
| defaultGhostColor | 对应颜色及状态的文字、背景或边框 |
| ghostBg | 对应颜色及状态的文字、背景或边框 |
| defaultGhostBorderColor | 对应颜色及状态的文字、背景或边框 |
| solidTextColor | 默认及预设实心按钮的显式文字色；不覆盖 primaryColor/dangerColor |
| textTextColor | 对应颜色及状态的文字、背景或边框 |
| textTextHoverColor | 对应颜色及状态的文字、背景或边框 |
| textTextActiveColor | 对应颜色及状态的文字、背景或边框 |
| paddingInline | 对应尺寸内边距 |
| paddingInlineLG | 对应尺寸内边距 |
| paddingInlineSM | 对应尺寸内边距 |
| paddingBlock | 对应尺寸内边距 |
| paddingBlockLG | 对应尺寸内边距 |
| paddingBlockSM | 对应尺寸内边距 |
| onlyIconSize | 仅图标尺寸 |
| onlyIconSizeLG | 仅图标尺寸 |
| onlyIconSizeSM | 仅图标尺寸 |
| linkHoverBg | 对应颜色及状态的文字、背景或边框 |
| textHoverBg | 对应颜色及状态的文字、背景或边框 |
| contentFontSize | 对应尺寸字号 |
| contentFontSizeLG | 对应尺寸字号 |
| contentFontSizeSM | 对应尺寸字号 |
| contentLineHeight | 对应尺寸行高 |
| contentLineHeightLG | 对应尺寸行高 |
| contentLineHeightSM | 对应尺寸行高 |
| defaultBgDisabled | 对应颜色及状态的文字、背景或边框 |
| dashedBgDisabled | 对应颜色及状态的文字、背景或边框 |

预设阴影：`blueShadowColor`, `purpleShadowColor`, `cyanShadowColor`, `greenShadowColor`, `magentaShadowColor`, `pinkShadowColor`, `redShadowColor`, `orangeShadowColor`, `yellowShadowColor`, `volcanoShadowColor`, `geekblueShadowColor`, `limeShadowColor`, `goldShadowColor`.

```vue
<ConfigProvider :theme="{components:{Button:{contentFontSize:18,paddingInline:24}}}">
  <Button type="primary">Save</Button>
</ConfigProvider>
```

主色与危险实心按钮默认使用 colorTextLightSolid，普通、悬停、按下均保持浅色文字，不使用自动黑白前景替换。支持相对颜色的浏览器会限制这些实心背景的过高亮度，保证默认白字可读性，保留全局 Alias 原值。默认及预设实心按钮保留自动前景；彩色文字保留原生 CSS 明度修正。显式前景 Token 和原生样式优先；自定义文字、透明及渐变表面须按实际背景配对。不支持的色值函数保留 Alias 回退，实际验证范围见审计记录。

Button、genButtonStyle、prepareButtonComponentToken 从 @apollo-design/ui 和 @apollo-design/ui/button 导出。类型含 ButtonProps、ButtonRef、ButtonSlots、ButtonSlot、ButtonConfig、上述枚举/语义类型、ButtonComponentToken、ButtonTokenInput。旧文档中的 button/style/token 不是包导出路径。

```ts
import '@apollo-design/theme/tokens.css';
import '@apollo-design/ui/button/style.css';
// Or import '@apollo-design/ui/style.css';
```

[契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/button-contracts.md)。


## 按钮类型 (basic)

`type` 是 v5 及更早版本的「糖」写法，v6 里会被解析成 `color` + `variant`：

| type | color | variant |
|---|---|---|
| `primary` | `primary` | `solid` |
| `default` | `default` | `outlined` |
| `dashed` | `default` | `dashed` |
| `text` | `default` | `text` |
| `link` | `link` | `link` |

最后一颗按钮演示「两个中文字符自动插空格」：`autoInsertSpace` 默认为 `true`。

### basic.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Button type="primary">Primary</Button>
    <Button>Default</Button>
    <Button type="dashed">Dashed</Button>
    <Button type="text">Text</Button>
    <Button type="link">Link</Button>
    <!-- 两个中文字符会自动视觉字距（-two-chinese-chars） -->
    <Button type="primary">确定</Button>
  </Space>
</template>
```

## 按钮尺寸 (size)

`size` 的默认档是 `medium`（旧写法 `middle` 同样合法），此时**不**输出 `-lg` / `-sm` 类名。

### size.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Button type="primary" size="large">Large</Button>
    <Button type="primary" size="medium">Medium</Button>
    <Button type="primary">Default</Button>
    <Button type="primary" size="small">Small</Button>
  </Space>
</template>
```

## 加载中 (loading)

`loading` 有两种形态：

- 布尔：`true` 立刻进入加载态。
- 对象：`{ delay, icon }`。`delay > 0` 时**延迟到点才置为加载态**，用于防止连点；
  变回 `false` **只能靠 `loading` prop 自己变回**，不会自动复位。

加载中时点击被拦截（`preventDefault` 且不 emit `click`）。

### loading.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
import { onUnmounted, ref } from 'vue';

const loading = ref(false);
const delayLoading = ref(false);
const count = ref(0);
let immediateTimer: ReturnType<typeof setTimeout> | undefined;
let delayedTimer: ReturnType<typeof setTimeout> | undefined;
function enter(delayed: boolean) {
  const current = delayed ? delayLoading : loading;
  if (current.value) return;
  current.value = true;
  count.value++;
  const finish = () => {
    current.value = false;
  };
  if (delayed) delayedTimer = setTimeout(finish, 3000);
  else immediateTimer = setTimeout(finish, 3000);
}
onUnmounted(() => {
  clearTimeout(immediateTimer);
  clearTimeout(delayedTimer);
});
</script>
<template>
  <Space orientation="vertical">
    <Space wrap>
      <Button type="primary" loading>Loading</Button>
      <Button type="primary" :loading="delayLoading ? { delay: 1000 } : false" @click="enter(true)">
        Delay 1s
      </Button>
      <Button type="primary" :loading="loading" @click="enter(false)">Click me</Button>
    </Space>
    <p aria-live="polite" style="margin:0;color:var(--apollo-color-text-secondary)">
      已触发 {{ count }} 次；加载请求立即阻止重复点击，1 秒只延迟指示器显示，3 秒后恢复。
    </p>
  </Space>
</template>
```

## 不可用状态 (disabled)

⚠️ 两个分支的 disabled 表达**不对称**，这是上游真实行为（不是笔误）：

| 分支 | 表现 |
|---|---|
| `<button>`（无 `href`） | 原生 `disabled` 属性 |
| `<a>`（有 `href`） | 移除 `href` + `tabindex="-1"` + `aria-disabled` |

### disabled.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Button type="primary">Primary</Button>
    <Button type="primary" disabled>Primary(disabled)</Button>
    <Button type="text">Text</Button>
    <Button type="text" disabled>Text(disabled)</Button>
    <Button type="link">Link</Button>
    <Button type="link" disabled>Link(disabled)</Button>
    <Button type="primary" href="https://example.com">Href</Button>
    <Button type="primary" href="https://example.com" disabled>Href(disabled)</Button>
  </Space>
</template>
```

## 危险按钮 (danger)

`danger` 会把解析出的 `color` 换成 `danger`。

⚠️ 类名上有**两处不一致**（上游真实行为）：

- `-dangerous` 用的是**原始 `danger` prop**
- `-color-dangerous` 里 danger 被改写成 `dangerous`（不是 `-color-danger`）

### danger.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Button type="primary" danger>Primary</Button>
    <Button danger>Default</Button>
    <Button type="dashed" danger>Dashed</Button>
    <Button type="text" danger>Text</Button>
    <Button type="link" danger>Link</Button>
  </Space>
</template>
```

## 幽灵按钮 (ghost)

幽灵按钮把背景变透明，常用在有色背景上。

⚠️ `ghost` 对 `solid` 变体的处理是**退化成 `outlined`**（不是加个类了事）。

⚠️ 属性顺序有讲究：`ghost` 必须写在 `danger` **之后**才不会被 `danger` 的样式压过。

### ghost.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, Space } from '@apollo-design/ui';
</script>
<template>
  <ConfigProvider :theme="{components:{Button:{defaultGhostColor:'var(--apollo-color-text)',defaultGhostBorderColor:'var(--apollo-color-border)'}}}">
    <div style="background:var(--apollo-color-fill-tertiary);padding:16px">
      <Space wrap>
        <Button type="primary" ghost>Primary</Button>
        <Button ghost>Default</Button>
        <Button type="dashed" ghost>Dashed</Button>
        <Button type="primary" danger ghost>Danger</Button>
      </Space>
    </div>
  </ConfigProvider>
</template>
```

## 块级按钮 (block)

`block` 让按钮撑满父容器宽度（`-block` 类名 → `width: 100%`）。

### block.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <Space orientation="vertical" style="width: 100%">
    <Button type="primary" block>Primary</Button>
    <Button block>Default</Button>
    <Button type="dashed" block>Dashed</Button>
  </Space>
</template>
```

## 图标按钮 (icon)

`icon` 在 v6 里是**节点**，不是 v4 的字符串名（传字符串且长度 > 2 会输出告警）。
也可以传**组件** —— Vue 没有 React 的「元素」形态，对应物就是组件本身（差异 D42）。

- `icon` prop 与 `icon` 插槽都能传图标，**prop 优先**（`props.icon ?? slots.icon()`）。
- `iconPlacement="end"` 把图标放到文字后面（靠 `-icon-end` 类名用 CSS 翻转，
  **不是**调换 DOM 顺序）。
- 没有默认插槽且有图标时加 `-icon-only` 类名。
- `loading` 时图标换成加载图标（`loading.icon` > ConfigProvider 的 `loadingIcon` > 内置 `LoadingOutlined`）。
  容器上额外带 `-loading-icon` 类名 —— ⚠️ **只在前两支都没提供自定义图标时才带**；
  一旦有自定义加载图标（prop 或 ConfigProvider），该类名**不出现**。
- 插槽仍只接受 `() => VNodeChild`；组件要走 prop。

### icon.vue

```vue
<script setup lang="ts">
import { SearchOutlined } from '@apollo-design/icons';
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Button type="primary" :icon="SearchOutlined">Search</Button>
    <Button :icon="SearchOutlined" icon-placement="end">Search</Button>
    <Button type="primary" :icon="SearchOutlined" aria-label="Search" />
    <!-- 用插槽传图标 -->
    <Button type="primary">
      <template #icon><SearchOutlined /></template>
      Slot icon
    </Button>
  </Space>
</template>
```

## 按钮形状 (shape)

`shape` 取 `default` 与 `square` 时**不**产出 `-{shape}` 类名，其余（`circle` / `round`）产出。

### shape.vue

```vue
<script setup lang="ts">
import { SearchOutlined } from '@apollo-design/icons';
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Button type="primary" shape="circle" :icon="SearchOutlined" aria-label="Search" />
    <Button type="primary" shape="round">Round</Button>
    <Button type="primary" shape="square">Square</Button>
    <Button shape="circle" :icon="SearchOutlined" aria-label="Search" />
    <Button shape="round">Round</Button>
  </Space>
</template>
```

## 颜色与变体 (color-variant)

`color` + `variant` 是 v6 的新写法，**同时给出时优先级最高**（压过 `type` / `danger`）。

- `color`：16 个预设语义色（含 `default` / `primary` / `danger` + 13 个色板色）
- `variant`：`outlined` / `dashed` / `solid` / `filled` / `text` / `link`

⚠️ `filled` 在 `ButtonTypeMap` 里**没有**映射 ⇒ 只能由 `variant` 显式传入。

### color-variant.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Button color="blue" variant="solid">Blue solid</Button>
    <Button color="purple" variant="outlined">Purple outlined</Button>
    <Button color="cyan" variant="filled">Cyan filled</Button>
    <Button color="green" variant="dashed">Green dashed</Button>
    <Button color="volcano" variant="text">Volcano text</Button>
    <Button color="gold" variant="link">Gold link</Button>
  </Space>
</template>
```

## 链接按钮 (href)

传了 `href` 就渲染 `<a>` 而不是 `<button>`。此时 `htmlType` 无效、没有原生 `disabled`，
禁用靠「移除 `href` + `tabindex="-1"` + `aria-disabled`」。

### href.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Button type="primary" href="https://example.com">Href</Button>
    <Button href="https://example.com" target="_blank">Href(target=_blank)</Button>
    <Button type="link" href="https://example.com">Link</Button>
  </Space>
</template>
```

## 语义化 classNames / styles (semantic)

`classNames` / `styles` 各有三个槽位：`root` / `icon` / `content`。

合并优先级（低 → 高）：



⚠️ 与 antd 的差异：本仓库**不支持函数式变体**（`classNames` / `styles` 只接受对象），
依据 `empty-semantic-fn` 开放决策的建议 B，与已完成的 divider / empty / space / spin 一致。

### semantic.vue

```vue
<script setup lang="ts">
import { SearchOutlined } from '@apollo-design/icons';
import { Button } from '@apollo-design/ui';
</script>

<template>
  <Button
    type="primary"
    :icon="SearchOutlined"
    :class-names="{ root: 'demo-btn-root', icon: 'demo-btn-icon', content: 'demo-btn-content' }"
    :styles="{ root: { borderRadius: '16px' }, content: { letterSpacing: '2px' } }"
  >
    Semantic
  </Button>
</template>
```

## 组件 Token (component-token)

通过当前 `ConfigProvider.theme.components.Button` 修改已有 Token，并保留 Alias 主色/圆角定制。支持动态配置、移除恢复、原生根变量覆盖；草稿和点击计数用于观察内容与状态是否保留。

主按钮默认使用浅色文字；“自定义主按钮文字”演示 `primaryColor` 的显式覆盖，关闭后恢复默认白字。浅色实心背景会限制过高亮度以保持文字可读性；自定义前景、渐变和透明背景需自行配对。

### component-token.vue

```vue
<script setup lang="ts">
import { Button, Checkbox, ConfigProvider, Input, Space } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const clicks = ref(0);
const enabled = ref(true);
const enlarged = ref(false);
const native = ref(false);
const customForeground = ref(false);
const theme = computed(() =>
  enabled.value
    ? {
        token: { colorPrimary: '#006b45', borderRadius: 16 },
        components: {
          Button: {
            ...(customForeground.value ? { primaryColor: '#fff6e6' } : {}),
            fontWeight: 600,
            iconGap: 12,
            paddingInline: 24,
            contentFontSize: enlarged.value ? 18 : 14,
            defaultBg: '#e8f5ee',
            defaultColor: '#123b2c',
            defaultBorderColor: '#33775b',
          },
        },
      }
    : undefined,
);
</script>
<template>
  <div class="demo-button-token">
    <fieldset>
      <legend>当前配置</legend>
      <Checkbox v-model:checked="enabled">启用组件 Token</Checkbox>
      <Checkbox v-model:checked="enlarged">放大字号</Checkbox>
      <Checkbox v-model:checked="native">原生变量优先</Checkbox>
      <Checkbox v-model:checked="customForeground">自定义主按钮文字</Checkbox>
    </fieldset>
    <ConfigProvider :theme="theme">
      <Space wrap>
        <Button type="primary" :style="native ? {'--apollo-btn-content-font-size':'22px'} : undefined" @click="clicks++">Primary</Button>
        <Button>Default</Button>
        <Button type="primary" danger>Danger</Button>
      </Space>
    </ConfigProvider>
    <label>保留草稿 <Input aria-label="Button token draft" placeholder="切换配置时保留输入和焦点" style="max-width: 280px" /></label>
    <p aria-live="polite" class="demo-button-token__hint">
      点击 Primary 次数：{{ clicks }}；切换或移除当前组件配置，原生根变量仍有最高优先级。
    </p>
  </div>
</template>
<style>
.demo-button-token {display:flex;flex-direction:column;gap:12px;font-family:var(--apollo-font-family);}
.demo-button-token fieldset {display:flex;flex-wrap:wrap;gap:12px;}
.demo-button-token__hint {margin:0;color:var(--apollo-color-text-secondary);font-size:12px;}
</style>
```

## 中文 loading (chinese-chars-loading)

两个中文字按钮在 `loading` 态下仍会保持自动插入的间距，可点击「提交」观察加载到完成的切换。

### chinese-chars-loading.vue

```vue
<script setup lang="ts">
// 两个中文字 + loading：视觉字距与加载态共存
import { Button, Space } from '@apollo-design/ui';
import { onUnmounted, ref } from 'vue';

const loading = ref(false);
const status = ref('未提交');
let timer: ReturnType<typeof setTimeout> | undefined;
onUnmounted(() => clearTimeout(timer));

function submit(): void {
  if (loading.value) return;
  loading.value = true;
  status.value = '提交中…';
  timer = setTimeout(() => {
    loading.value = false;
    status.value = '提交完成';
  }, 1500);
}
</script>

<template>
  <Space orientation="vertical" :size="12" style="font-family: sans-serif">
    <Space wrap>
      <Button type="primary" loading>确定</Button>
      <Button loading>取消</Button>
      <Button type="primary" :loading="loading" @click="submit">提交</Button>
    </Space>
    <div aria-live="polite" style="font-size: 12px; color: var(--apollo-color-text-secondary)">
      状态：{{ status }}（loading 图标与两个中文字之间仍保持自动间距）
    </div>
  </Space>
</template>
```

## 中文间距 (chinese-space)

`autoInsertSpace` 控制两个中文字之间是否自动插入空格，默认开启；对比点击可观察间距差异。

### chinese-space.vue

```vue
<script setup lang="ts">
// autoInsertSpace：两个中文字之间是否自动视觉字距（默认 true）
import { Button, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const last = ref('');
</script>

<template>
  <Space orientation="vertical" :size="12" style="font-family: sans-serif">
    <Space wrap>
      <Button @click="last = '确定（默认视觉字距）'">确定</Button>
      <Button @click="last = '取消（默认视觉字距）'">取消</Button>
      <Button :auto-insert-space="false" @click="last = '确定（autoInsertSpace=false）'">确定</Button>
      <Button :auto-insert-space="false" @click="last = '取消（autoInsertSpace=false）'">取消</Button>
    </Space>
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">最近点击：{{ last || '-' }}</div>
  </Space>
</template>
```

## 图标位置 (icon-placement)

`iconPlacement` 取 `'start'` 或 `'end'`，控制 `icon` 相对文字的位置；仅图标按钮可配合 `shape="circle"`。

### icon-placement.vue

```vue
<script setup lang="ts">
// iconPlacement：图标在文字之前或之后
import { SearchOutlined } from '@apollo-design/icons';
import { Button, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const last = ref('');
</script>

<template>
  <div style="font-family: sans-serif">
    <Space wrap>
      <Button
        type="primary"
        :icon="SearchOutlined"
        icon-placement="start"
        @click="last = 'start'"
      >
        搜索
      </Button>
      <Button type="primary" :icon="SearchOutlined" icon-placement="end" @click="last = 'end'">搜索</Button>
      <Button :icon="SearchOutlined" icon-placement="end" @click="last = 'default-end'">设置</Button>
      <Button
        type="primary"
        :icon="SearchOutlined"
        shape="circle"
        aria-label="搜索"
        @click="last = 'circle'"
      />
    </Space>
    <div style="margin-top: 12px; font-size: 12px; color: var(--apollo-color-text-secondary)">
      最近点击的图标位置：{{ last || '-' }}
    </div>
  </div>
</template>
```

## 自定义禁用背景 (custom-disabled-bg)

通过 `ConfigProvider` 的 `theme.token` 覆盖 `colorBgContainerDisabled`、`colorBorderDisabled` 与 `colorTextDisabled`，统一改变禁用按钮配色。

### custom-disabled-bg.vue

```vue
<script setup lang="ts">
// 自定义禁用态背景 / 边框 / 文字色（ConfigProvider theme.token）
import { Button, ConfigProvider, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const clicks = ref(0);
</script>

<template>
  <div style="font-family: sans-serif">
    <ConfigProvider
      :theme="{
        token: {
          colorBgContainerDisabled: '#e6f4ff',
          colorBorderDisabled: '#91caff',
          colorTextDisabled: '#1677ff',
        },
      }"
    >
      <Space wrap>
        <Button disabled>Default(disabled)</Button>
        <Button type="primary" disabled>Primary(disabled)</Button>
        <Button danger disabled>Danger(disabled)</Button>
        <Button type="primary" @click="clicks++">可点击 {{ clicks }}</Button>
      </Space>
    </ConfigProvider>
    <div style="margin-top: 12px; font-size: 12px; color: var(--apollo-color-text-secondary)">
      上方禁用按钮的背景 / 边框 / 文字来自 ConfigProvider 的 theme.token 覆盖
    </div>
  </div>
</template>
```

## 线性渐变 (linear-gradient)

用自定义类覆盖主按钮的 `background-image`，实现线性渐变；悬停与按下状态使用同色系更亮的渐变。禁用按钮保留组件自身的禁用样式。

### linear-gradient.vue

```vue
<script setup lang="ts">
// 线性渐变：用类名覆盖主按钮背景
import { Button, Space } from '@apollo-design/ui';
</script>

<template>
  <div class="demo-button-gradient-wrap">
    <Space wrap>
      <Button class="demo-button-gradient" type="primary" size="large">Linear Gradient</Button>
      <Button class="demo-button-gradient demo-button-gradient--warm" type="primary">
        Warm Gradient
      </Button>
      <Button class="demo-button-gradient" type="primary" disabled>Disabled Gradient</Button>
    </Space>
    <p class="demo-button-gradient__hint">
      渐变只覆盖背景图像，悬停与按下状态保持同色系，并为白色文字配对足够深的渐变端点。
    </p>
  </div>
</template>

<style>
.demo-button-gradient.apollo-btn {
  color: #fff;
  border: 0;
  background-image: linear-gradient(135deg, #0958d9 0%, #531dab 100%);
  box-shadow: 0 6px 16px rgb(22 119 255 / 28%);
}

.demo-button-gradient.apollo-btn:not(:disabled):hover {
  color: #fff;
  background-image: linear-gradient(135deg, #0958d9 0%, #722ed1 100%);
  box-shadow: 0 8px 20px rgb(114 46 209 / 30%);
}

.demo-button-gradient.apollo-btn:not(:disabled):active {
  color: #fff;
  background-image: linear-gradient(135deg, #0958d9 0%, #531dab 100%);
}

.demo-button-gradient--warm.apollo-btn {
  background-image: linear-gradient(135deg, #b33a00 0%, #a8071a 100%);
  box-shadow: 0 6px 16px rgb(245 34 45 / 26%);
}

.demo-button-gradient--warm.apollo-btn:not(:disabled):hover {
  background-image: linear-gradient(135deg, #c43d00 0%, #a8071a 100%);
}

.demo-button-gradient.apollo-btn:disabled {
  background-image: none;
  color: var(--apollo-color-text-disabled);
}

.demo-button-gradient-wrap {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

.demo-button-gradient__hint {
  margin: 0;
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

## 多个按钮 (multiple)

把一组相关按钮放进 `role="group"` 容器并设置 `aria-label`，辅助技术会把它们读作一个操作组。每个按钮都有可见文本，点击结果通过 `aria-live` 区域反馈。

### multiple.vue

```vue
<script setup lang="ts">
// 多个按钮组合：用 role="group" 提供可访问的操作组语义
import { Button, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const lastAction = ref('尚未操作');

function run(action: string): void {
  lastAction.value = action;
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <div role="group" aria-label="文档操作">
      <Space wrap>
        <Button type="primary" @click="run('编辑')">编辑</Button>
        <Button @click="run('复制')">复制</Button>
        <Button @click="run('分享')">分享</Button>
        <Button danger @click="run('删除')">删除</Button>
      </Space>
    </div>
    <p aria-live="polite" style="margin: 0; color: var(--apollo-color-text-secondary); font-size: 12px">
      最近操作：{{ lastAction }}
    </p>
  </div>
</template>
```

## 语义化样式与类 (style-class)

Button 提供 `root` / `content` / `icon` 三个语义槽。`classNames` 拼接类名，`styles` 覆盖对应槽位的样式；示例分别调整根节点圆角与内边距、文本字距和图标颜色。

### style-class.vue

```vue
<script setup lang="ts">
// 语义化样式与类：root / content / icon 三个槽位
import { SearchOutlined } from '@apollo-design/icons';
import type { ButtonProps } from '@apollo-design/ui';
import { Button, Space } from '@apollo-design/ui';

const classNames: ButtonProps['classNames'] = {
  root: 'demo-button-style',
  content: 'demo-button-style__content',
  icon: 'demo-button-style__icon',
};

const styles: ButtonProps['styles'] = {
  root: { borderRadius: '18px', paddingInline: '20px' },
  content: { letterSpacing: '1px' },
  icon: { fontSize: '20px' },
};
</script>

<template>
  <div class="demo-button-style-wrap">
    <Space wrap>
      <Button type="primary" :icon="SearchOutlined" :class-names="classNames" :styles="styles">
        查询
      </Button>
      <Button :class-names="classNames" :styles="styles">默认按钮</Button>
      <Button type="dashed" :class-names="classNames" :styles="styles" disabled>禁用按钮</Button>
    </Space>
    <p class="demo-button-style-wrap__hint">
      root 控制圆角与内边距，content 控制字距，icon 单独设置字号。
    </p>
  </div>
</template>

<style>
.demo-button-style {
  border-color: #d3adf7;
}

.demo-button-style__content {
  font-weight: 500;
}

.demo-button-style-wrap {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

.demo-button-style-wrap__hint {
  margin: 0;
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

---

# Calendar

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/calendar


在内联的月历或年度月份面板中展示与选择日期。

## 示例

[`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/calendar/demo) 保留九个示例，包含原生表头/单元格插槽与当前组件 Token。

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 已接收日期，支持 `v-model:value` | `CalendarDate`（Dayjs） | — |
| defaultValue | 非受控初值；后续修改不重置当前状态 | `CalendarDate` | 今天 |
| mode | 已接收模式，支持 `v-model:mode` | `'month' \| 'year'` | `'month'` |
| fullscreen | 全屏日历；false 为卡片尺寸 | `boolean` | `true` |
| showWeek | 显示周号 | `boolean` | `false` |
| validRange | 可选日期闭区间，端点可选 | `[CalendarDate, CalendarDate]` | — |
| disabledDate | 额外禁用判定，与范围越界取“或” | `(date: CalendarDate) => boolean` | — |
| locale | 与当前 `ConfigProvider.locale.Calendar` 深合并 | `PickerLocale` | 当前语言 |
| classNames | 六个语义目标；对象或读取当前 props 的函数 | `CalendarSemanticValue<CalendarSemanticClassNames, CalendarProps>` | — |
| styles | 六个语义目标；对象或读取当前 props 的函数 | `CalendarSemanticValue<CalendarSemanticStyles, CalendarProps>` | — |
| prefixCls | 面板类名前缀 | `string` | 当前根前缀 + `-picker` |

原生 class、Vue 全部 style 形态、id、ARIA/data 属性、tabindex 和普通 DOM 监听器落在实际根 div。原生 style 在主题、Provider 与本地语义样式之后合并。组件所属通知由 Vue emits 消费。

受控模型只发更新提议。被父级拒绝的提议不会写入隐藏本地状态；撤控保留最后实际接收的值/模式。默认值仅在非受控初始化时使用。

### 插槽

| 插槽 | 作用域 | 行为 |
|---|---|---|
| `headerRender` | `{ value, type, onChange, onTypeChange }`（`CalendarHeaderRenderConfig`） | 替换表头。两个命令通过 Calendar 正常链路请求日期/模式更新。 |
| `cellRender` | `{ current, info }`（`CalendarCellSlotProps`） | 默认日期/月份标签下方的内容。 |
| `fullCellRender` | `{ current, info }`（`CalendarCellSlotProps`） | 替换包含标签的完整单元格；优先于 cellRender。 |

`current` 是 Dayjs 日期；`info` 复用 PickerPanel 的 `CalendarCellRenderInfo`，包含 type、locale、originNode。插槽在渲染时读取，条件增删即时生效；数组、文本、0 与显式空内容保留 Vue 原义。

```vue
<Calendar v-model:value="date" v-model:mode="mode">
  <template #headerRender="{ value, type, onChange, onTypeChange }">
    <button @click="onChange(value.add(1, 'month'))">下个月</button>
    <button @click="onTypeChange(type === 'month' ? 'year' : 'month')">{{ type }}</button>
  </template>
  <template #cellRender="{ current }">{{ events[current.format('YYYY-MM-DD')] }}</template>
</Calendar>
```

迁移：headerRender、cellRender、fullCellRender 内容 prop 以及四个旧 date/month 内容 prop 已移除，直接使用同名具名槽；日期/月内容用 info.type 区分。不保留回调兜底或弃用通道。disabledDate 继续承担真实判定服务。

### 事件

| 事件 | 载荷 |
|---|---|
| `update:value` | `(date: CalendarDate)` |
| `change` | `(date: CalendarDate)` |
| `update:mode` | `(mode: CalendarMode)` |
| `panelChange` | `(date: CalendarDate, mode: CalendarMode)` |
| `select` | `(date: CalendarDate, info: { source: 'date' \| 'month' \| 'year' \| 'customize' })` |

日期请求依次发 update:value、跨月（月模式）或跨年（年模式）时的 panelChange、change、select。同一天只发 select。模式请求仅在不同值时发 update:mode，随后发带当前日期的 panelChange。面板的 select source 为 date 或 month；自定义表头日期命令为 customize。

### Ref

`nativeElement: HTMLDivElement | null` 返回实际根，卸载后为 null。不提供额外 focus/blur 命令；内部面板与控件保留自身原生键盘/焦点行为。

## 配置与主题

语义目标为 root、header、body、content、item、itemContent。后四个传递给 PickerPanel，itemContent 也作用于 Calendar 默认内容容器。函数读取当前公开 props；fullscreen 已解析默认 true，mode 保留原始 prop。返回 undefined 表示本次不贡献覆盖。

`ConfigProvider.components.calendar` 提供展示默认配置；`ConfigProvider.theme.components.Calendar` 提供六个组件 Token。替换和撤除均更新现有实例。

| Token | 类型 | 默认值 |
|---|---|---|
| fullBg | string | colorBgContainer |
| fullPanelBg | string | colorBgContainer |
| itemActiveBg | string | controlItemBgActive |
| yearControlWidth | number 或 CSS 长度字符串 | 80 |
| monthControlWidth | number 或 CSS 长度字符串 | 70 |
| miniContentHeight | number 或 CSS 长度字符串 | 256 |

数字长度转换为 px，包含 0。继续使用静态 CSS 与既有 21 个共享面板变量；类名与变量命名空间不同（apollo-picker-calendar 与 --apollo-calendar-*）。自定义类名前缀需配套生成对应样式。


## 基本 (basic)

一个通用的日历面板，支持年/月切换。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo。
//
// ⚠️ 上游的 `Calendar` 不传 `value` ⇒ 内部取 `getNow()`（默认「今天」）。
//    demo 是给人看的，保持这个行为；**视觉/契约用例**则必须显式传 `value`（否则会 flaky）。

import type { CalendarEmits } from '@apollo-design/ui';
import { Calendar } from '@apollo-design/ui';

const onPanelChange: CalendarEmits['panelChange'] = (value, mode) => {
  console.log(value.format('YYYY-MM-DD'), mode);
};
</script>

<template>
  <Calendar @panel-change="onPanelChange" />
</template>
```

## 卡片式 (card)

用于嵌套在空间有限的容器中。

### card.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 card demo：迷你日历 + 自绘边框容器。
//
// 边框与圆角直接消费 CSS 变量，跟随当前亮暗主题。

import type { CalendarEmits } from '@apollo-design/ui';
import { Calendar } from '@apollo-design/ui';

const onPanelChange: CalendarEmits['panelChange'] = (value, mode) => {
  console.log(value.format('YYYY-MM-DD'), mode);
};

const wrapperStyle = {
  width: '300px',
  maxWidth: '100%',
  boxSizing: 'border-box' as const,
  border: '1px solid var(--apollo-color-border-secondary)',
  borderRadius: 'var(--apollo-border-radius-lg)',
};
</script>

<template>
  <div :style="wrapperStyle">
    <Calendar :fullscreen="false" @panel-change="onPanelChange" />
  </div>
</template>
```

## 自定义头部 (customize-header)

自定义日历头部内容。

### customize-header.vue

```vue
<script setup lang="ts">
import type { CalendarDate, CalendarMode, RadioValue, SelectValue } from '@apollo-design/ui';
import { Calendar, Flex, RadioButton, RadioGroup, Select } from '@apollo-design/ui';
import dayjs from 'dayjs';

const years = (value: CalendarDate) =>
  Array.from({ length: 20 }, (_, offset) => ({
    label: value.year() - 10 + offset,
    value: value.year() - 10 + offset,
  }));
const months = Array.from({ length: 12 }, (_, month) => ({
  label: dayjs().month(month).format('MMM'),
  value: month,
}));
function selectDate(
  next: SelectValue,
  value: CalendarDate,
  change: (date: CalendarDate) => void,
  unit: 'year' | 'month',
) {
  if (typeof next === 'number') change(unit === 'year' ? value.year(next) : value.month(next));
}
function selectMode(next: RadioValue, change: (mode: CalendarMode) => void) {
  if (next === 'month' || next === 'year') change(next);
}
const onPanelChange = (value: CalendarDate, mode: CalendarMode) =>
  console.log(value.format('YYYY-MM-DD'), mode);
const wrapperStyle = {
  width: '300px',
  maxWidth: '100%',
  boxSizing: 'border-box' as const,
  border: '1px solid var(--apollo-color-border-secondary)',
  borderRadius: 'var(--apollo-border-radius-lg)',
};
</script>

<template>
  <div :style="wrapperStyle">
    <Calendar :fullscreen="false" @panel-change="onPanelChange">
      <template #headerRender="{ value, type, onChange, onTypeChange }">
        <div style="padding: 8px">
          <h4 style="margin: 0 0 8px">Custom header</h4>
          <Flex :gap="8" wrap>
            <RadioGroup size="small" :value="type" @update:value="next => selectMode(next, onTypeChange)">
              <RadioButton value="month">Month</RadioButton>
              <RadioButton value="year">Year</RadioButton>
            </RadioGroup>
            <Select aria-label="Year" size="small" :value="value.year()" :options="years(value)" @update:value="next => selectDate(next, value, onChange, 'year')" />
            <Select aria-label="Month" size="small" :value="value.month()" :options="months" @update:value="next => selectDate(next, value, onChange, 'month')" />
          </Flex>
        </div>
      </template>
    </Calendar>
  </div>
</template>
```

## 跨日期事件 (event-range)

通过 `cellRender` 渲染跨日期事件。此示例使用已有的 `styles.itemContent`，仅允许自己的色条跨出日期内容层；普通日历事件列表仍保留默认的固定高度与纵向滚动。

色条按当前日历语言的实际周首日分段，跨周换行时重新显示标题并保留两端圆角，不把不同行连在一起。1 月 17–20 日的事件展示这种换行；RTL 使用逻辑方向边距。窄屏标题保持省略显示，完整名称保留在原生 `title` 中。

The existing `styles.itemContent` scopes visible overflow to this example. Ordinary event lists keep their fixed-height vertical scrolling. Bars split at the current locale's week boundaries, repeat their title on each row, and use logical margins in RTL. Narrow cells retain ellipsis and the complete native title.

### event-range.vue

```vue
<script setup lang="ts">
// Continuous bars use the demo's content layer; ordinary Calendar lists keep scrolling.
import { dayjsGenerateConfig } from '@apollo-design/picker';
import { Calendar } from '@apollo-design/ui';
import dayjs from 'dayjs';

interface CalendarEvent {
  key: string;
  title: string;
  start: dayjs.Dayjs;
  end: dayjs.Dayjs;
  color: string;
}

/** 色值 = 默认主题的 `colorPrimary` / `colorSuccess` / `colorWarning` / `colorError`。 */
const EVENTS: CalendarEvent[] = [
  {
    key: 'release',
    title: 'Release window',
    start: dayjs('2026-01-08'),
    end: dayjs('2026-01-10'),
    color: '#1677ff',
  },
  {
    key: 'design-review',
    title: 'Design review',
    start: dayjs('2026-01-14'),
    end: dayjs('2026-01-14'),
    color: '#52c41a',
  },
  {
    key: 'cross-week',
    title: 'Cross-week delivery',
    start: dayjs('2026-01-17'),
    end: dayjs('2026-01-20'),
    color: '#1677ff',
  },
  {
    key: 'maintenance',
    title: 'Maintenance',
    start: dayjs('2026-01-21'),
    end: dayjs('2026-01-24'),
    color: '#faad14',
  },
  {
    key: 'bug-fix',
    title: 'Bug fix',
    start: dayjs('2026-01-30'),
    end: dayjs('2026-01-31'),
    color: '#ff4d4f',
  },
];

/** 上游 `defaultValue={dayjs('2026-01-01')}` —— 锚定到有事件的那个月。 */
const defaultValue = dayjs('2026-01-01');

const isInRange = (current: dayjs.Dayjs, event: CalendarEvent) =>
  !current.isBefore(event.start, 'day') && !current.isAfter(event.end, 'day');

type RangePosition = 'single' | 'start' | 'middle' | 'end';

const getRangePosition = (
  current: dayjs.Dayjs,
  event: CalendarEvent,
  weekFirstDay: number,
): RangePosition => {
  const starts = current.isSame(event.start, 'day') || current.day() === weekFirstDay;
  const ends = current.isSame(event.end, 'day') || current.day() === (weekFirstDay + 6) % 7;
  if (starts && ends) return 'single';
  if (starts) return 'start';
  if (ends) return 'end';
  return 'middle';
};

const getCellEvents = (current: dayjs.Dayjs, locale: string) => {
  // Use the same locale service as PickerPanel, including Monday/Saturday weeks.
  const firstDay = dayjsGenerateConfig.locale.getWeekFirstDay(locale);
  return EVENTS.filter((event) => isInRange(current, event)).map((event) => ({
    event,
    position: getRangePosition(current, event, firstDay),
  }));
};

/** 色条圆角（上游 `barRadius = 999`）。 */
const BAR_RADIUS = '999px';
/** `marginXXS` / `controlHeightSM` / `fontSizeSM` / `paddingXS` / `marginXS` / `paddingXXS` 的默认值。 */
const MARGIN_XXS = 4;
const CONTROL_HEIGHT_SM = 24;
const FONT_SIZE_SM = 12;
const PADDING_XS = 8;
const MARGIN_XS = 8;
const PADDING_XXS = 4;

const barStyle = {
  display: 'block',
  height: `${CONTROL_HEIGHT_SM - MARGIN_XXS}px`,
  overflow: 'hidden',
  color: '#fff',
  fontSize: `${FONT_SIZE_SM}px`,
  whiteSpace: 'nowrap',
  textOverflow: 'ellipsis',
} as const;

const rangeStyle: Record<RangePosition, Record<string, string>> = {
  start: {
    marginInlineEnd: `${-(PADDING_XS + MARGIN_XS / 2)}px`,
    paddingInlineStart: `${PADDING_XXS + PADDING_XXS}px`,
    borderStartStartRadius: BAR_RADIUS,
    borderEndStartRadius: BAR_RADIUS,
  },
  middle: { marginInline: `${-(PADDING_XS + MARGIN_XS / 2)}px` },
  end: {
    marginInlineStart: `${-(PADDING_XS + MARGIN_XS / 2)}px`,
    borderStartEndRadius: BAR_RADIUS,
    borderEndEndRadius: BAR_RADIUS,
  },
  single: { paddingInlineStart: `${PADDING_XXS + PADDING_XXS}px`, borderRadius: BAR_RADIUS },
};
</script>

<template>
  <Calendar :default-value="defaultValue" :styles="{ itemContent: { overflow: 'visible' } }">
    <template #cellRender="{ current, info }">
      <div v-if="info.type === 'date'" :style="{ minHeight: '32px', paddingBlockStart: `${MARGIN_XXS}px` }">
        <div :style="{ display: 'flex', flexDirection: 'column', gap: `${MARGIN_XXS}px` }">
          <span v-for="{ event, position } in getCellEvents(current, info.locale.locale)" :key="event.key"
            :data-event="event.key" :data-position="position" :title="event.title"
            :style="{ ...barStyle, ...rangeStyle[position], backgroundColor: event.color }">
            {{ ['start', 'single'].includes(position) ? event.title : '' }}
          </span>
        </div>
      </div>
    </template>
  </Calendar>
</template>
```

## 通知事项日历 (notice-calendar)

一个复杂的应用示例，用 `cellRender` 来自定义需要渲染的数据。

### notice-calendar.vue

```vue
<script setup lang="ts">
import type { BadgeProps } from '@apollo-design/ui';
import { Badge, Calendar } from '@apollo-design/ui';
import type dayjs from 'dayjs';

const getListData = (
  value: dayjs.Dayjs,
): { type: NonNullable<BadgeProps['status']>; content: string }[] => {
  switch (value.date()) {
    case 8:
      return [
        { type: 'warning', content: 'This is warning event.' },
        { type: 'success', content: 'This is usual event.' },
      ];
    case 10:
      return [
        { type: 'warning', content: 'This is warning event.' },
        { type: 'success', content: 'This is usual event.' },
        { type: 'error', content: 'This is error event.' },
      ];
    case 15:
      return [
        { type: 'warning', content: 'This is warning event' },
        { type: 'success', content: 'This is very long usual event......' },
        { type: 'error', content: 'This is error event 1.' },
        { type: 'error', content: 'This is error event 2.' },
        { type: 'error', content: 'This is error event 3.' },
        { type: 'error', content: 'This is error event 4.' },
      ];
    default:
      return [];
  }
};

const getMonthData = (value: dayjs.Dayjs): number | undefined =>
  value.month() === 8 ? 1394 : undefined;
</script>

<template>
  <Calendar>
    <template #cellRender="{ current, info }">
      <ul v-if="info.type === 'date'" style="margin: 0; padding: 0; list-style: none">
        <li v-for="item in getListData(current)" :key="item.content">
          <Badge :status="item.type" :text="item.content" />
        </li>
      </ul>
      <div v-else-if="info.type === 'month' && getMonthData(current) !== undefined" style="font-size: 28px; text-align: center">
        <section style="font-size: 28px">{{ getMonthData(current) }}</section>
        <span>Backlog number</span>
      </div>
    </template>
  </Calendar>
</template>
```

## 选择日期 (select)

受控用法：`@select` 记录选中日期，`@panel-change` 记录面板浏览值。

### select.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 select demo：受控 `value` + `onSelect` / `onPanelChange`。
//
// ⚠️ 本仓把回调放在 **emits** 里（`@select` / `@panel-change`），`value` 走
//    `v-model:value` 的通道（C11：`update:value` 与 `change` 双发）。

import type { CalendarDate } from '@apollo-design/ui';
import { Alert, Calendar } from '@apollo-design/ui';
import dayjs from 'dayjs';
import { computed, ref } from 'vue';

const value = ref<CalendarDate>(dayjs('2017-01-25'));
const selectedValue = ref<CalendarDate>(dayjs('2017-01-25'));

const onSelect = (newValue: CalendarDate) => {
  value.value = newValue;
  selectedValue.value = newValue;
};

const onPanelChange = (newValue: CalendarDate) => {
  value.value = newValue;
};

const title = computed(() => `You selected date: ${selectedValue.value?.format('YYYY-MM-DD')}`);
</script>

<template>
  <Alert :title="title" />
  <Calendar v-model:value="value" @select="onSelect" @panel-change="onPanelChange" />
</template>
```

## 语义化样式 (style-class)

通过 `classNames` 和 `styles` 传入对象/函数可以自定义 Calendar 的语义化结构样式。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo：`classNames` 与 `styles` 的**对象 / 函数**两种形态。
//
// ⚠️ **一处 demo 级替换**：上游用 `antd-style` 的 `createStyles` 生成类名 ——
//    本仓是**零运行时**架构，没有 CSS-in-JS ⇒ 用 SFC 的 `<style>` 块定义同名类名
//    （效果等价：`classNames.root` 拿到一个带 `padding` + 背景色的类）。

import type { CalendarProps } from '@apollo-design/ui';
import { Calendar, Flex } from '@apollo-design/ui';

/** 对象形态：`borderRadius` / `width` 直接给值。 */
const stylesObject: CalendarProps['styles'] = {
  root: {
    borderRadius: 8,
    width: 600,
    maxWidth: '100%',
    boxSizing: 'border-box',
  },
};

/**
 * 函数形态：按 `info.props` 决定返回什么。
 * ⚠️ `info.props.fullscreen` 是**解析后**的值（未传 ⇒ `true`）——
 *    与上游 `{...props, mode, fullscreen, showWeek}` 的语义一致（`mode` 保持原始 prop）。
 */
const stylesFunction: CalendarProps['styles'] = (info) => {
  if (info.props.fullscreen) {
    return {
      root: {
        border: '2px solid var(--apollo-color-success-border)',
        borderRadius: 10,
        backgroundColor: 'var(--apollo-color-success-bg)',
      },
    };
  }
  return undefined;
};
</script>

<template>
  <Flex gap="medium" vertical>
    <Calendar :fullscreen="false" :class-names="{ root: 'calendar-root' }" :styles="stylesObject" />
    <Calendar :class-names="{ root: 'calendar-root' }" :styles="stylesFunction" />
  </Flex>
</template>

<style>
.calendar-root {
  padding: 10px;
  background-color: var(--apollo-color-primary-bg);
}
</style>
```

## 周数 (week)

通过将 `showWeek` 属性设置为 `true`，在全屏日历中显示周数。

### week.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 week demo：全屏与迷你两种形态都开 `showWeek`。

import { Calendar } from '@apollo-design/ui';
</script>

<template>
  <Calendar :fullscreen="true" :show-week="true" />
  <br />
  <Calendar :fullscreen="false" :show-week="true" />
</template>
```

## 组件 Token (component-token)

通过 `ConfigProvider.theme.components.Calendar` 当前配置覆盖六个组件 Token；长度支持数字和 CSS 字符串，替换或撤除即时更新。原生 style 中的 CSS 变量仍可用于局部覆盖。

农历（`lunar`）需要第三方 `lunar-typescript`，本仓未移植，因此示例不包含农历场景。

### component-token.vue

```vue
<script setup lang="ts">
import type { CalendarDate } from '@apollo-design/ui';
import { Calendar, ConfigProvider } from '@apollo-design/ui';
import dayjs from 'dayjs';
import { ref } from 'vue';

const value = ref<CalendarDate>(dayjs('2026-10-15'));
const theme = {
  components: {
    Calendar: {
      fullBg: 'var(--apollo-color-success-bg)',
      fullPanelBg: 'var(--apollo-color-success-bg)',
      itemActiveBg: 'var(--apollo-color-success-bg-hover)',
      yearControlWidth: 96,
      monthControlWidth: '80px',
      miniContentHeight: 288,
    },
  },
};
</script>

<template>
  <ConfigProvider :theme="theme">
    <Calendar v-model:value="value" :fullscreen="false" />
  </ConfigProvider>
</template>
```

---

# Card

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/card


通用卡片容器。

## 何时使用

- 最基础的卡片容器，可承载文字、列表、图片、段落，常用于后台概览页面；
- 需要把一组相关信息聚合在一个容器里，并与周围内容区分开时。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/card/demo)（**12 个**，覆盖 antd 的主要用户场景）。

| demo | 内容 |
|---|---|
| `basic` | 典型卡片（含 `size="small"` 的对照） |
| `border-less` | `variant="borderless"` 的无边框卡片 |
| `simple` | 只包含内容区域（无 head） |
| `flexible-content` | `cover` + `Card.Meta` 的灵活内容 |
| `in-column` | 与栅格配合 |
| `loading` | `loading` ⇒ body 里是 Skeleton |
| `grid-card` | `Card.Grid` 的内容区隔 |
| `inner` | `type="inner"` 的内部卡片 |
| `tabs` | `tabList` 的页签卡片 |
| `meta` | 封面 + 头像 + 标题 + 描述 |

`style-class` 与 `component-token` 已包含在当前 12 个 Demo 中；前者展示语义样式，后者展示当前 Provider 组件 Token。历史差额保留在 README 的原日期记录中。

## API

### Card

| 参数 | 说明 | 类型 | 默认值 | 全局配置 |
|---|---|---|---|---|
| title | 卡片标题；**支持插槽 `#title`**（插槽优先） | `VNodeChild` | — | × |
| extra | 右上角操作区；**支持插槽 `#extra`** | `VNodeChild` | — | × |
| cover | 封面；**支持插槽 `#cover`** | `VNodeChild` | — | × |
| actions | 操作区 VNode 数据列表；支持 actions 槽（每项包一层 `<li><span>`，宽度均分） | `VNodeChild[]` | — | × |
| loading | 加载中（内容替换成 `Skeleton`） | `boolean` | `false` | × |
| hoverable | 悬浮时显示阴影与手型光标 | `boolean` | `false` | × |
| size | 尺寸 | `'medium' \| 'small' \| 'middle' \| 'default'` | `medium` | ✅（`componentSize`） |
| type | 卡片类型（目前只有 `'inner'`） | `'inner'` | — | × |
| variant | 形态。`'borderless'` ⇒ 不加 `-bordered`、改用三级阴影 | `'outlined' \| 'borderless'` | `outlined` | ✅（`card.variant`） |
| tabList | 页签列表。⚠️ `tab` 已废弃，用 `label` | `CardTabListType[]` | — | × |
| activeTabKey | 当前页签，支持 v-model:active-tab-key；undefined 撤控后保留最后接收值 | `string` | — | × |
| defaultActiveTabKey | 非受控的初始页签 | `string` | — | × |
| tabBarExtraContent | 页签栏两侧的附加内容 | `VNodeChild \| { left, right }` | — | × |
| tabProps | 透传给内部 `Tabs` 的 props | `TabsProps` | — | × |
| classNames | 语义化类名（7 槽），支持函数形态 | `CardSemanticClassNames \| ((info) => …)` | — | ✅（`card.classNames`） |
| styles | 语义化样式（7 槽），支持函数形态 | `CardSemanticStyles \| ((info) => …)` | — | ✅（`card.styles`） |
| prefixCls | 类名前缀（**根前缀本身**，不是后缀） | `string` | 从 ConfigProvider 取，兜底 `apollo-card` | × |
| class / style | **根元素原生 attrs**（不是 Props） | `string \| array \| object` / `CSSProperties` | — | × |
| id | 根元素 id | `string` | — | × |
| bordered | ⚠️ **已废弃**，用 `variant` | `boolean` | — | × |
| headStyle | ⚠️ **已废弃**，用 `styles.header` | `CSSProperties` | — | × |
| bodyStyle | ⚠️ **已废弃**，用 `styles.body` | `CSSProperties` | — | × |

> ⚠️ 语义化槽**覆盖** deprecated 的 `headStyle` / `bodyStyle`（合并顺序是
> `{...headStyle, ...mergedStyles.header}`）。

### 事件

`tabChange(key: string)` 与 `update:activeTabKey(key: string)` 是所属事件。使用 `@tab-change` 监听通知、`v-model:active-tab-key` 接收更新。JSX 的 `onTabChange` 是同一事件的 listener 拼法，组件不另行调用回调。

定义了 activeTabKey 时，更新是父级可接受或拒绝的提议；拒绝后撤控不会泄漏未接收值。defaultActiveTabKey 只设置初值。tabProps 的 activeKey/defaultActiveKey、items 与 tabBarExtraContent 不改变 Card 对应字段的归属，其余 Tabs 配置、VNode 标签及有返回值的服务函数保持透传。

### 插槽

| 名称 | 说明 |
|---|---|
| default | 卡片内容；loading 时以真实 Skeleton 替换，不求值隐藏内容 |
| title / extra / cover | 对应内容，存在即优先于 prop，含显式空槽；动态添加/撤除即时生效 |
| actions | 操作项列表；支持条件项与 Fragment，使用唯一 VNode key 保留项身份 |

### Card.Meta

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| avatar | 头像；**支持插槽 `#avatar`** | `VNodeChild` | — |
| title | 标题；**支持插槽 `#title`** | `VNodeChild` | — |
| description | 描述；**支持插槽 `#description`** | `VNodeChild` | — |
| classNames | 语义化类名（`root` / `section` / `avatar` / `title` / `description`） | `CardMetaSemanticClassNames \| ((info) => …)` | — |
| styles | 语义化样式（同上五个槽） | `CardMetaSemanticStyles \| ((info) => …)` | — |
| prefixCls | 类名前缀（**card 的前缀**：传 `x` ⇒ `x-meta`） | `string` | 兜底 `apollo-card` |
| class / style | 根元素原生 attrs | `string` / `CSSProperties` | — |

插槽：avatar、title、description，以及 description 后备内容的 default。优先顺序为 description 槽（存在即优先，含显式空）→ 显式 description 数据（含 0/null/false）→ default。avatar/title 槽也遵循存在即优先。

> ⚠️ `avatar` 在 `section` **外面**，`title` / `description` 在 **里面**；
> 根上**没有** `-rtl`（`Card.Meta` 不读 `direction`）。

### Card.Grid

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| hoverable | 悬浮高亮。⚠️ **默认 `true`**（与 `Card` 的默认 `false` 不同） | `boolean` | `true` |
| prefixCls | 类名前缀（**card 的前缀**：传 `x` ⇒ `x-grid`） | `string` | 兜底 `apollo-card` |
| class / style | 根元素原生 attrs | `string` / `CSSProperties` | — |

### 实例方法（ref）

三个组件都暴露 `{ nativeElement }`（`HTMLDivElement | null`）。

> ⚠️ 上游 `Card` 是 `forwardRef<HTMLDivElement>`（ref 就是 DOM 元素本身），
> `Card.Grid` / `Card.Meta` 是 `{ nativeElement }`。本仓**统一成对象**（差异见 `README.md` §2 第 1 条）。

### 语义化 DOM

| 槽 | `Card` 的落点 | `Card.Meta` 的落点 |
|---|---|---|
| `root` | 根 `<div class="{prefixCls}">` | 根 `<div class="{prefixCls}-meta">` |
| `header` / `section` | `<div class="{prefixCls}-head">` | `<div class="{prefixCls}-meta-section">` |
| `body` / `avatar` | `<div class="{prefixCls}-body">` | `<div class="{prefixCls}-meta-avatar">` |
| `extra` / `title` | `<div class="{prefixCls}-extra">` | `<div class="{prefixCls}-meta-title">` |
| `title` / `description` | `<div class="{prefixCls}-head-title">` | `<div class="{prefixCls}-meta-description">` |
| `actions` | `<ul class="{prefixCls}-actions">` | — |
| `cover` | `<div class="{prefixCls}-cover">` | — |

## Theme

### Component Token（13 个）

| token | 说明 | 默认值 |
|---|---|---|
| `headerBg` | 卡片头部背景色 | `transparent` |
| `headerFontSize` | 卡片头部文字大小 | `fontSizeLG` |
| `headerFontSizeSM` | 小号卡片头部文字大小 | `fontSize` |
| `headerHeight` | 卡片头部高度 | `fontSizeLG * lineHeightLG + padding * 2` |
| `headerHeightSM` | 小号卡片头部高度 | `fontSize * lineHeight + paddingXS * 2` |
| `actionsBg` | 操作区背景色 | `colorBgContainer` |
| `actionsLiMargin` | 操作区每一项的外间距 | `${paddingSM}px 0` |
| `tabsMarginBottom` | 内置标签页组件下间距 | `-padding - lineWidth` |
| `extraColor` | 额外区文字颜色 | `colorText` |
| `bodyPaddingSM` | 小号卡片内边距 | `12` |
| `headerPaddingSM` | 小号卡片头部内边距 | `12` |
| `bodyPadding` | 卡片内边距 | `paddingLG` |
| `headerPadding` | 卡片头部内边距 | `paddingLG` |

> ⚠️ 上游的 `bodyPadding` / `headerPadding` 写的是 `token.bodyPadding ?? token.paddingLG`，
> 但那个键**不在** antd 6 的 `AliasToken` 里（v4 遗留）⇒ 实际恒取 `paddingLG`。
> 本仓直接写 `paddingLG`（见 `README.md` §2 第 2 条）。

当前 13 个 Token 从 `ConfigProvider theme.components.Card` 与当前别名主题派生，支持替换和撤除；Grid/Meta 独立使用也读取当前主题。函数式 classNames/styles 读取当前生效的尺寸、形态和 Props。Card 不读取 Form 的输入形态；继承的 large 尺寸解析成 medium。

原生 class/style、属性和监听器落到实际根元素；直接 CSS 变量覆盖优先于主题和语义根样式。运行时也可用 CSS 变量：`--apollo-card-header-height` / `--apollo-card-body-padding` /
`--apollo-card-actions-bg` 等（13 个，变量名与 antd 的 `--ant-card-*` 同构）。


## 基本 (basic)

包含标题、内容、操作区域。

`size` 支持 `medium`（默认）与 `small`。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo。
import { Card, Space } from '@apollo-design/ui';
import { h } from 'vue';

const more = () => h('a', { href: '#' }, 'More');
</script>

<template>
  <Space vertical :size="16" style="width: 100%">
    <Card title="Default size card" :extra="more()" :style="{ width: '300px', maxWidth: '100%' }">
      <p>Card content</p>
      <p>Card content</p>
      <p>Card content</p>
    </Card>
    <Card size="small" title="Small size card" :extra="more()" :style="{ width: '300px', maxWidth: '100%' }">
      <p>Card content</p>
      <p>Card content</p>
      <p>Card content</p>
    </Card>
  </Space>
</template>
```

## 无边框 (border-less)

在灰色背景上使用无边框的卡片。

`variant="borderless"` 时不加 `-bordered` 类名，改用三级阴影（`boxShadowTertiary`）。

### border-less.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 border-less demo。
import { Card } from '@apollo-design/ui';
</script>

<template>
  <div style="padding: 24px; background: var(--apollo-color-fill-alter); border-radius: var(--apollo-border-radius-lg)">
    <Card title="Card title" variant="borderless" :style="{ width: '300px', maxWidth: '100%' }">
      <p>Card content</p>
      <p>Card content</p>
      <p>Card content</p>
    </Card>
  </div>
</template>
```

## 简洁卡片 (simple)

只包含内容区域。

没有 `title` / `extra` / `tabList` ⇒ **不渲染 head**（`isRenderable` 判据）。

### simple.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 simple demo。
import { Card } from '@apollo-design/ui';
</script>

<template>
  <Card :style="{ width: '300px', maxWidth: '100%' }">
    <p>Card content</p>
    <p>Card content</p>
    <p>Card content</p>
  </Card>
</template>
```

## 更灵活的内容展示 (flexible-content)

可以利用 `Card.Meta` 支持更灵活的内容。

⚠️ 封面用 **data URI** 而不是外网图片（与 `image` / `avatar` 的 demo 同判：外网图片会污染 L6 基线）。

### flexible-content.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 flexible-content demo。
// ⚠️ 封面用 **data URI**（外网图片会污染 L6 基线，与 image/avatar 的 demo 同判）。
import { Card, CardMeta } from '@apollo-design/ui';
import { h } from 'vue';

// Original vector illustration; no third-party image or network dependency.
const COVER = `data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="480" height="300" viewBox="0 0 480 300"><rect width="480" height="300" fill="#cce5f0"/><circle cx="370" cy="70" r="38" fill="#fff0bf"/><path d="M0 205L115 88l115 117 95-75 155 140v30H0z" fill="#477f96"/><path d="M0 250l155-110 95 110 100-58 130 88v20H0z" fill="#244e67"/></svg>')}`;

const cover = () => h('img', { draggable: false, alt: 'Original mountain landscape', src: COVER });
</script>

<template>
  <Card hoverable variant="borderless" :style="{ width: '240px', maxWidth: '100%' }" :cover="cover()">
    <CardMeta title="Europe Street beat" description="www.instagram.com" />
  </Card>
</template>
```

## 栅格卡片 (in-column)

在系统概览页面常常和栅格进行配合。

### in-column.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 in-column demo。
import { Card, Col, Row } from '@apollo-design/ui';
</script>

<template>
  <Row :gutter="[16, 16]" style="padding: 24px; background: var(--apollo-color-fill-alter); border-radius: var(--apollo-border-radius-lg)">
    <Col :xs="24" :sm="8">
      <Card title="Card title" variant="borderless">Card content</Card>
    </Col>
    <Col :xs="24" :sm="8">
      <Card title="Card title" variant="borderless">Card content</Card>
    </Col>
    <Col :xs="24" :sm="8">
      <Card title="Card title" variant="borderless">Card content</Card>
    </Col>
  </Row>
</template>
```

## 预加载的卡片 (loading)

数据读入前会有文本块样式。

`loading` 时 body 里的内容被替换成 `Skeleton`（`active` + 4 行段落 + **无标题行**）。

头像使用本库 `Avatar`，保留离线可用的文字内容。

### loading.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 loading demo。
import { EditOutlined, EllipsisOutlined, SettingOutlined } from '@apollo-design/icons';
import { Avatar, Card, CardMeta, Flex, Switch } from '@apollo-design/ui';
import { h, ref, type VNodeChild } from 'vue';

const loading = ref(true);

const actions = [
  h(EditOutlined, { key: 'edit' }),
  h(SettingOutlined, { key: 'setting' }),
  h(EllipsisOutlined, { key: 'ellipsis' }),
];

const avatar = (text: string): VNodeChild => h(Avatar, null, () => text);

const description = () => [
  h('p', null, 'This is the description'),
  h('p', null, 'This is the description'),
];
</script>

<template>
  <Flex gap="medium" align="start" vertical>
    <Switch
      aria-label="Show card content"
      :checked="!loading"
      @change="(checked: boolean) => (loading = !checked)"
    />
    <Card :loading="loading" :actions="actions" :style="{ width: '300px', maxWidth: '100%' }">
      <CardMeta :avatar="avatar('A')" title="Card title" :description="description()" />
    </Card>
    <Card :loading="loading" :actions="actions" :style="{ width: '300px', maxWidth: '100%' }">
      <CardMeta :avatar="avatar('B')" title="Card title" :description="description()" />
    </Card>
  </Flex>
</template>
```

## 网格型内嵌卡片 (grid-card)

一种常见的卡片内容区隔模式。

`Card.Grid` 的 `hoverable` **默认 `true`**（与 `Card` 的默认 `false` 不同）；有 `Card.Grid`
子元素时根上会加 `-contain-grid`，body 变成 `flex-wrap` 容器。

### grid-card.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 grid-card demo。
import { Card, CardGrid } from '@apollo-design/ui';
import type { CSSProperties } from 'vue';

const gridStyle: CSSProperties = { width: '25%', textAlign: 'center' };
</script>

<template>
  <Card title="Card Title">
    <CardGrid :style="gridStyle">Content</CardGrid>
    <CardGrid :hoverable="false" :style="gridStyle">Content</CardGrid>
    <CardGrid :style="gridStyle">Content</CardGrid>
    <CardGrid :style="gridStyle">Content</CardGrid>
    <CardGrid :style="gridStyle">Content</CardGrid>
    <CardGrid :style="gridStyle">Content</CardGrid>
    <CardGrid :style="gridStyle">Content</CardGrid>
  </Card>
</template>
```

## 内部卡片 (inner)

可以放在普通卡片内部，展示多层级结构的信息。

`type="inner"` 时根上加 `-type-inner`：head 背景变 `colorFillAlter`、字号降一档、
body 的上下 padding 变成 `padding`（左右仍是 `bodyPadding`）。

### inner.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 inner demo。
import { Card } from '@apollo-design/ui';
import { h } from 'vue';

const more = () => h('a', { href: '#' }, 'More');
</script>

<template>
  <Card title="Card title">
    <Card type="inner" title="Inner Card title" :extra="more()">Inner Card content</Card>
    <Card
      :style="{ marginTop: '16px' }"
      type="inner"
      title="Inner Card title"
      :extra="more()"
    >
      Inner Card content
    </Card>
  </Card>
</template>
```

## 带页签的卡片 (tabs)

使用 `v-model:active-tab-key` 接收页签更新；`@tab-change="handler"` 监听同一次切换通知。`defaultActiveTabKey` 只设置非受控初值，定义了 `activeTabKey` 时以当前值为准；撤控后保留最后接收值。`tabList` 的数据 VNode 与 `tab` / `label` 通道继续支持。

### tabs.vue

```vue
<script setup lang="ts">
import { Card } from '@apollo-design/ui';
import { h, ref } from 'vue';

const tabList = [
  { key: 'tab1', tab: 'tab1' },
  { key: 'tab2', tab: 'tab2' },
];

const contentList: Record<string, string> = {
  tab1: 'content1',
  tab2: 'content2',
};

const tabListNoTitle = [
  { key: 'article', label: 'article' },
  { key: 'app', label: 'app' },
  { key: 'project', label: 'project' },
];

const contentListNoTitle: Record<string, string> = {
  article: 'article content',
  app: 'app content',
  project: 'project content',
};

const activeTabKey1 = ref('tab1');
const activeTabKey2 = ref('app');

const more = () => h('a', { href: '#' }, 'More');
</script>

<template>
  <Card
    :style="{ width: '100%' }"
    title="Card title"
    :extra="more()"
    :tab-list="tabList"
    v-model:active-tab-key="activeTabKey1"
  >
    <p>{{ contentList[activeTabKey1] }}</p>
  </Card>
  <br />
  <br />
  <Card
    :style="{ width: '100%' }"
    :tab-list="tabListNoTitle"
    v-model:active-tab-key="activeTabKey2"
    :tab-bar-extra-content="more()"
    :tab-props="{ size: 'medium' }"
  >
    <p>{{ contentListNoTitle[activeTabKey2] }}</p>
  </Card>
</template>
```

## 支持更多内容配置 (meta)

一种支持封面、头像、标题和描述信息的卡片。默认槽可提供描述后备内容：description 槽存在时优先（含显式空）；否则优先使用显式 description 数据（含 0、null、false），最后才使用默认槽。

`Card.Meta` 的 `avatar` 在 `section` **外面**，`title` / `description` 在 **里面**。

封面使用原创内嵌 SVG，头像使用本库 `Avatar`，无需外网图片。

### meta.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 meta demo。
// 本地原创 SVG 封面可离线展示。
import { EditOutlined, EllipsisOutlined, SettingOutlined } from '@apollo-design/icons';
import { Avatar, Card, CardMeta } from '@apollo-design/ui';
import { h, type VNodeChild } from 'vue';

// Original vector illustration; no third-party image or network dependency.
const COVER = `data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="480" height="300" viewBox="0 0 480 300"><rect width="480" height="300" fill="#cce5f0"/><circle cx="370" cy="70" r="38" fill="#fff0bf"/><path d="M0 205L115 88l115 117 95-75 155 140v30H0z" fill="#477f96"/><path d="M0 250l155-110 95 110 100-58 130 88v20H0z" fill="#244e67"/></svg>')}`;

const cover = () => h('img', { draggable: false, alt: 'Original mountain landscape', src: COVER });

const actions = [
  h(SettingOutlined, { key: 'setting' }),
  h(EditOutlined, { key: 'edit' }),
  h(EllipsisOutlined, { key: 'ellipsis' }),
];

const avatar = (text: string): VNodeChild => h(Avatar, null, () => text);
</script>

<template>
  <Card :style="{ width: '300px', maxWidth: '100%' }" :cover="cover()" :actions="actions">
    <CardMeta :avatar="avatar('A')" title="Card title">This is the description</CardMeta>
  </Card>
</template>
```

## 组件 Token (component-token)

通过 `ConfigProvider theme.components.Card` 设置当前组件 Token，定制头部背景、字号、内边距与操作区背景；配置替换与撤除会同步生效。原生 `style` 中的 `--apollo-card-*` 变量仍可作局部覆盖。

悬浮卡片可以看到阴影反馈。

### component-token.vue

```vue
<script setup lang="ts">
import type { ThemeConfig } from '@apollo-design/theme';
import { Card, ConfigProvider } from '@apollo-design/ui';

const tokenStyle = {
  width: '360px',
  maxWidth: '100%',
};
const theme: ThemeConfig = {
  components: {
    Card: {
      headerBg: 'var(--apollo-color-primary-bg)',
      headerFontSize: 18,
      headerPadding: 24,
      bodyPadding: 20,
      actionsBg: 'var(--apollo-color-primary-bg)',
    },
  },
};

const actions = ['Edit', 'More'];
</script>

<template>
  <ConfigProvider :theme="theme">
    <Card
      title="Component token card"
      extra="Extra"
      hoverable
      :actions="actions"
      :style="tokenStyle"
    >
      <p>Card content</p>
      <p>Header, body and actions are styled with card component tokens.</p>
    </Card>
  </ConfigProvider>
</template>
```

## 语义化样式 (style-class)

通过 `classNames` 与 `styles` 自定义卡片根节点、头部、内容区、标题、额外区与操作区的样式。

悬浮卡片可以看到阴影反馈。

### style-class.vue

```vue
<script setup lang="ts">
// 语义化 classNames / styles：root / header / body / title / extra / actions。
import { Card } from '@apollo-design/ui';

const classNames = {
  root: 'demo-card-style-root',
  header: 'demo-card-style-header',
  body: 'demo-card-style-body',
  title: 'demo-card-style-title',
  extra: 'demo-card-style-extra',
  actions: 'demo-card-style-actions',
};

const styles = {
  body: {
    background:
      'linear-gradient(180deg, var(--apollo-color-primary-bg) 0%, var(--apollo-color-bg-container) 100%)',
  },
  title: { color: 'var(--apollo-color-primary-text)' },
  extra: { fontSize: '14px' },
};

const actions = ['Edit', 'More'];
</script>

<template>
  <Card
    title="Semantic styles"
    extra="Extra"
    hoverable
    :actions="actions"
    :class-names="classNames"
    :styles="styles"
  >
    <p>Card content</p>
    <p>Use semantic classNames and styles to customize each part of the card.</p>
  </Card>
</template>

<style>
.demo-card-style-root {
  width: 360px;
  max-width: 100%;
  border: 1px solid var(--apollo-color-border);
}

.demo-card-style-header {
  letter-spacing: 0.01em;
}

.demo-card-style-actions {
  color: var(--apollo-color-primary);
}
</style>
```

---

# Carousel

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/carousel


# Carousel

通过原生默认插槽提供轮播内容。示例见 [demo](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/carousel/demo)（保留现有九个示例）。

## API

| 属性 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| effect | 动画效果 | `'scrollx' \| 'fade'` | `'scrollx'` |
| dots | 显示圆点，可提供内层圆点类 | `boolean \| { className?: string }` | `true` |
| dotPlacement | 圆点位置；start/end默认启用纵向 | `'top' \| 'bottom' \| 'start' \| 'end'` | `'bottom'` |
| dotPosition | 已有位置别名；请用dotPlacement | `DotPlacement \| 'left' \| 'right'` | `—` |
| autoplay | 自动播放；对象形态启用圆点进度 | `boolean \| { dotDuration?: boolean }` | `false` |
| autoplaySpeed | 播放间隔配置，毫秒 | `number` | `3000` |
| speed | 动画时长，毫秒 | `number` | `500` |
| cssEase | 实际CSS过渡缓动 | `string` | `'ease'` |
| infinite | 循环轮播，包含克隆实例 | `boolean` | `true` |
| initialSlide | 初始索引；动态变更重新定位 | `number` | `0` |
| slidesToShow | 可见页数；fade强制为1 | `number` | `1` |
| slidesToScroll | 每次翻页数；fade强制为1 | `number` | `1` |
| draggable | 鼠标拖拽 | `boolean` | `true` |
| swipe | 允许手势切换 | `boolean` | `true` |
| touchMove | 响应鼠标/触摸移动 | `boolean` | `true` |
| touchThreshold | 最小位移的除数：可视尺寸/该值 | `number` | `5` |
| vertical | 纵向布局；未传时从位置推导 | `boolean` | `—` |
| waitForAnimate | 动画中拒绝新切换 | `boolean` | `false` |
| pauseOnHover | 内容悬停时暂停 | `boolean` | `true` |
| pauseOnDotsHover | 圆点悬停时暂停 | `boolean` | `false` |
| pauseOnFocus | 本组件内聚焦时暂停 | `boolean` | `false` |
| arrows | 显示前后原生按钮 | `boolean` | `false` |
| accessibility | 启用轮播键盘操作和list焦点入口 | `boolean` | `true` |
| adaptiveHeight | list高度跟随当前页 | `boolean` | `false` |
| rtl | 水平RTL；默认读取当前Provider方向 | `boolean` | `—` |
| useCSS | 启用CSS切换动画 | `boolean` | `true` |
| useTransform | 使用transform；false时使用left/top | `boolean` | `true` |
| edgeFriction | 非循环边缘拖拽阻力 | `number` | `0.35` |
| prefixCls | 根类名前缀 | `string` | `'apollo-carousel'` |
| id | 实际根div的id | `string` | `—` |
| classNames | 内层语义类名 | `{ slider?: string }` | `—` |
| styles | 内层语义样式 | `{ slider?: CSSProperties }` | `—` |
| className | 已有内层类名别名，落点不变；新代码用classNames.slider | `string` | `—` |

原生 `class`、完整 `style`（对象、字符串、数组）、ARIA/data 与监听器落到实际根 div。原内层 `style` prop 直接移除，内层样式使用 `styles.slider`；已有不冲突的 `className` 仍落内层。Provider 的 `components.carousel` 类名/语义样式及当前方向响应替换和撤回。

`easing` 原来没有消费实现，开发阶段直接删除；缓动使用实际工作的 `cssEase`。没有兼容通道。

### 插槽

| 插槽 | 作用 | 参数 |
| --- | --- | --- |
| default | 完整 Vue 轮播内容；数组、Fragment、条件空内容和0均可处理 | — |
| prev-arrow / next-arrow | 既有原生箭头按钮的完整内容 | `{ currentSlide: number, slideCount: number }` |

箭头的禁用、名称、点击和键盘行为由原生 button 拥有。旧箭头槽中的 button 根直接改为图标/span等内容，避免嵌套按钮；多个内容节点和条件空槽不再被截断。自定义内容出现时不叠加默认箭头图形。

### 事件

| 事件 | 模板 | 参数 |
| --- | --- | --- |
| beforeChange | `@before-change` | `(current: number, next: number)` |
| afterChange | `@after-change` | `(current: number)` |
| swipe | `@swipe` | `('left' \| 'right' \| 'up' \| 'down')` |
| edge | `@edge` | 同上，非循环边缘拖拽 |
| keydown | `@keydown` | 原生 `KeyboardEvent`；先于导航，可 `preventDefault()` |

`h()` 使用 `onBeforeChange` / `onAfterChange` 等自然监听器。通知由 Vue emits 派发，不手调 attrs。没有 value 模型；定位通过公开方法。完成的滑动只通知一次，非切换的同位置请求不伪造切换。

### 引用与交互

```ts
interface CarouselRef {
  nativeElement: HTMLDivElement | null;
  goTo(slide: number, dontAnimate?: boolean): void;
  next(): void;
  prev(): void;
  autoPlay(playType?: 'update' | 'leave' | 'blur'): void;
  innerSlider: Readonly<CarouselEngineState>;
}
```

`innerSlider` 是实际响应式引擎状态，非 slick 实例。`goTo` 对有限索引按当前页数循环或约束；关闭动画时立即完成。动态配置/slide结构变化会收尾已接受的旧动画并按当前配置重测，旧计时器不能回写旧布局。`initialSlide` 或有效RTL改变会按当前初值重新定位。

方向键支持原生 key（并保留 keyCode），水平RTL交换左右方向，纵向支持上下方向。输入框、选择框、textarea、可编辑内容、输入法和已取消的事件不触发轮播导航。原始可交互内容保留其原生 Tab 行为；当前不可见内容使用 inert/aria-hidden，静止视口中可见的边界克隆保持交互。自动播放保留既有 `autoplaySpeed + 50` 调度，焦点、内容/圆点悬停原因合并，本实例的内移焦点不会提前恢复。

原始 slide 使用用户 key 保持组件身份。克隆树内已知原生 id 与指向这些 id 的 for/ARIA 关联带稳定的实例后缀，外部ID和自定义组件业务id不改。原件ref归原件；组件透传内容槽在实际渲染时只调用一次并保留作用域/owner，克隆返回节点清理ref。

克隆仍是独立组件实例，不镜像任意内部未受控状态；需要单一组件实例的内容可使用 `infinite=false`。没有探测或改写组件内部不可见的固定ID，也不预调用其插槽来搜集内部结构。

## 主题

保留八项：`arrowSize`、`arrowOffset`、`dotWidth`、`dotHeight`、`dotGap`、`dotOffset`、`dotWidthActive`、`dotActiveWidth`。全部接受数字(px)或CSS长度字符串，当前 `theme.components.Carousel` 替换/撤回生效。`dotWidthActive` 是既有别名，未设置新版字段时供应 `dotActiveWidth`；新版显式值优先。箭头尖角随当前 arrowSize 用 CSS calc 派生，支持 rem 等长度。原生根 style 中的变量可显式覆盖。

不支持的旧 slick 能力（responsive、rows、variableWidth、lazyLoad、asNavFor、appendDots/customPaging 等）没有在本轮新增。已有参考和算法证据保留；全库九维验收在最终冻结版本统一进行。


## 基本 (basic)

最简单的用法：默认 `infinite` 循环 + 底部圆点；`@after-change` 收到当前索引。

### basic.vue

```vue
<script setup lang="ts">
import './slides.css';
// 对齐 antd 的 basic demo
import { Carousel } from '@apollo-design/ui';

const onChange = (current: number) => {
  console.log(`current slide: ${current}`);
};
</script>

<template>
  <Carousel class="demo-carousel-slides" @after-change="onChange">
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #364d79">1</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #626c91">2</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #1677ff">3</h3></div>
  </Carousel>
</template>
```

### slides.css

```css
/* The sample slides use a fixed blue artwork surface in every theme. */
.demo-carousel-slides.apollo-carousel .slick-dots li button,
.demo-carousel-slides.apollo-carousel .slick-dots li.slick-active::after {
  background: var(--apollo-color-text-light-solid);
}
```

## 自动播放 (autoplay)

定时自动切换；`autoplay` 传对象并开启 `dotDuration` 时，当前圆点播放进度动画（时长即 `autoplaySpeed`）。

### autoplay.vue

```vue
<script setup lang="ts">
import './slides.css';
// 对齐 antd 的 autoplay demo（含圆点进度动画的对象形态）
import { Carousel } from '@apollo-design/ui';
</script>

<template>
  <Carousel class="demo-carousel-slides" :autoplay="{ dotDuration: true }" :autoplay-speed="3000">
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #364d79">1</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #626c91">2</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #1677ff">3</h3></div>
  </Carousel>
</template>
```

### slides.css

```css
/* The sample slides use a fixed blue artwork surface in every theme. */
.demo-carousel-slides.apollo-carousel .slick-dots li button,
.demo-carousel-slides.apollo-carousel .slick-dots li.slick-active::after {
  background: var(--apollo-color-text-light-solid);
}
```

## 淡入淡出 (fade)

`effect="fade"` 切换为淡入淡出（此时不渲染 clone 节点，slidesToShow/ToScroll 强制 1）。

### fade.vue

```vue
<script setup lang="ts">
import './slides.css';
// 对齐 antd 的 fade demo
import { Carousel } from '@apollo-design/ui';
</script>

<template>
  <Carousel class="demo-carousel-slides" effect="fade">
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #364d79">1</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #626c91">2</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #1677ff">3</h3></div>
  </Carousel>
</template>
```

### slides.css

```css
/* The sample slides use a fixed blue artwork surface in every theme. */
.demo-carousel-slides.apollo-carousel .slick-dots li button,
.demo-carousel-slides.apollo-carousel .slick-dots li.slick-active::after {
  background: var(--apollo-color-text-light-solid);
}
```

## 箭头 (arrows)

`arrows` 显示左右切换箭头（antd 默认无箭头）；自定义箭头用 `#prev-arrow` / `#next-arrow` 插槽（插槽作用域提供 `currentSlide` / `slideCount`）。

### arrows.vue

```vue
<script setup lang="ts">
import './slides.css';
// 对齐 antd 的 ArrowShow / CustomArrows demo：默认箭头 + 插槽自定义箭头
import { Carousel } from '@apollo-design/ui';
</script>

<template>
  <Carousel class="demo-carousel-slides" arrows>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #364d79">1</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #626c91">2</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #1677ff">3</h3></div>
  </Carousel>
</template>
```

### slides.css

```css
/* The sample slides use a fixed blue artwork surface in every theme. */
.demo-carousel-slides.apollo-carousel .slick-dots li button,
.demo-carousel-slides.apollo-carousel .slick-dots li.slick-active::after {
  background: var(--apollo-color-text-light-solid);
}
```

## 位置 (position)

圆点位置 `dotPlacement`：`top` / `bottom` / `start` / `end`（start/end 自动进入纵向布局；deprecated 的 `dotPosition` 的 left/right 会映射到 start/end 并发告警）。

### position.vue

```vue
<script setup lang="ts">
import './slides.css';
// 对齐 antd 的 Position demo：dotPlacement 四向（deprecated 的 dotPosition 同样可用）
import { Carousel } from '@apollo-design/ui';
</script>

<template>
  <Carousel class="demo-carousel-slides" dots-class="custom-dots" dot-placement="start" style="height: 160px">
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #364d79">1</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #626c91">2</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #1677ff">3</h3></div>
  </Carousel>
</template>
```

### slides.css

```css
/* The sample slides use a fixed blue artwork surface in every theme. */
.demo-carousel-slides.apollo-carousel .slick-dots li button,
.demo-carousel-slides.apollo-carousel .slick-dots li.slick-active::after {
  background: var(--apollo-color-text-light-solid);
}
```

## 拖拽 (drag)

`draggable` 开启鼠标拖拽（触摸滑动由 `swipe` 控制，默认开启）；拖到边界有 `edgeFriction` 橡皮筋阻尼。

### drag.vue

```vue
<script setup lang="ts">
import './slides.css';
// 对齐 antd 的 Draggeries demo（鼠标拖拽，触屏滑动恒可用）
import { Carousel } from '@apollo-design/ui';
</script>

<template>
  <Carousel class="demo-carousel-slides" draggable>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #364d79">1</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #626c91">2</h3></div>
    <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #1677ff">3</h3></div>
  </Carousel>
</template>
```

### slides.css

```css
/* The sample slides use a fixed blue artwork surface in every theme. */
.demo-carousel-slides.apollo-carousel .slick-dots li button,
.demo-carousel-slides.apollo-carousel .slick-dots li.slick-active::after {
  background: var(--apollo-color-text-light-solid);
}
```

## 定制组件 Token (component-token)

Component Token 即 CSS 变量（`--apollo-carousel-*`），在容器上覆盖同名变量即可定制圆点 / 箭头几何。

### component-token.vue

```vue
<script setup lang="ts">
import './slides.css';
// Current component tokens are projected to the real Carousel root.
import { Carousel, ConfigProvider } from '@apollo-design/ui';
</script>

<template>
  <ConfigProvider :theme="{ components: { Carousel: { arrowSize: 24, arrowOffset: 12, dotWidth: 24, dotHeight: 6, dotActiveWidth: 48, dotOffset: 20, dotGap: 6 } } }">
    <Carousel class="demo-carousel-slides" arrows>
      <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #364d79">1</h3></div>
      <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #626c91">2</h3></div>
      <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #1677ff">3</h3></div>
    </Carousel>
  </ConfigProvider>
</template>
```

### slides.css

```css
/* The sample slides use a fixed blue artwork surface in every theme. */
.demo-carousel-slides.apollo-carousel .slick-dots li button,
.demo-carousel-slides.apollo-carousel .slick-dots li.slick-active::after {
  background: var(--apollo-color-text-light-solid);
}
```

## 圆点进度动画 (dot-duration)

`autoplay` 传对象并开启 `dotDuration` 时，当前圆点按 `autoplaySpeed` 播放进度动画；开关可实时切换。

### dot-duration.vue

```vue
<script setup lang="ts">
import './slides.css';
// 对齐 antd 的 `dot-duration` demo：autoplay 对象形态开启圆点进度动画。
import type { CarouselAutoplay } from '@apollo-design/ui';
import { Carousel, Switch, Text } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const autoplay = ref(true);
const dotDuration = ref(true);
const current = ref(0);

const autoplayConfig = computed<boolean | CarouselAutoplay>(() =>
  autoplay.value ? { dotDuration: dotDuration.value } : false,
);

const onAfterChange = (index: number) => {
  current.value = index;
};
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 16px; margin-bottom: 12px">
      <Text>autoplay</Text>
      <Switch v-model:checked="autoplay" aria-label="自动播放" />
      <Text>dotDuration</Text>
      <Switch v-model:checked="dotDuration" aria-label="圆点进度动画" />
      <Text type="secondary">current: {{ current }}</Text>
    </div>
    <Carousel class="demo-carousel-slides" :autoplay="autoplayConfig" :autoplay-speed="3000" @after-change="onAfterChange">
      <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #364d79">1</h3></div>
      <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #626c91">2</h3></div>
      <div><h3 style="height: 160px; color: #fff; line-height: 160px; text-align: center; background: #1677ff">3</h3></div>
    </Carousel>
  </div>
</template>
```

### slides.css

```css
/* The sample slides use a fixed blue artwork surface in every theme. */
.demo-carousel-slides.apollo-carousel .slick-dots li button,
.demo-carousel-slides.apollo-carousel .slick-dots li.slick-active::after {
  background: var(--apollo-color-text-light-solid);
}
```

## 圆点位置 (placement)

`dotPlacement` 支持 `top` / `bottom` / `start` / `end`，用 `Segmented` 切换；start/end 自动进入纵向布局。

### placement.vue

```vue
<script setup lang="ts">
import './slides.css';
// 对齐 antd 6.6.4 的 `placement` demo：dotPlacement 四向切换。
import type { DotPlacement, SegmentedValue } from '@apollo-design/ui';
import { Carousel, Segmented, Text } from '@apollo-design/ui';
import { ref } from 'vue';

const dotPlacement = ref<DotPlacement>('bottom');
const current = ref(0);

const options: { label: string; value: DotPlacement }[] = [
  { label: 'Top', value: 'top' },
  { label: 'Bottom', value: 'bottom' },
  { label: 'Start', value: 'start' },
  { label: 'End', value: 'end' },
];

const onPlacementChange = (value: SegmentedValue) => {
  if (value === 'top' || value === 'bottom' || value === 'start' || value === 'end')
    dotPlacement.value = value;
};

const onAfterChange = (index: number) => {
  current.value = index;
};
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 12px; margin-bottom: 12px">
      <Segmented :value="dotPlacement" :options="options" @change="onPlacementChange" />
      <Text type="secondary">current: {{ current }}</Text>
    </div>
    <Carousel class="demo-carousel-slides" :dot-placement="dotPlacement" style="height: 180px" @after-change="onAfterChange">
      <div><h3 style="height: 180px; color: #fff; line-height: 180px; text-align: center; background: #364d79">1</h3></div>
      <div><h3 style="height: 180px; color: #fff; line-height: 180px; text-align: center; background: #626c91">2</h3></div>
      <div><h3 style="height: 180px; color: #fff; line-height: 180px; text-align: center; background: #1677ff">3</h3></div>
    </Carousel>
  </div>
</template>
```

### slides.css

```css
/* The sample slides use a fixed blue artwork surface in every theme. */
.demo-carousel-slides.apollo-carousel .slick-dots li button,
.demo-carousel-slides.apollo-carousel .slick-dots li.slick-active::after {
  background: var(--apollo-color-text-light-solid);
}
```

---

# Cascader

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/cascader


# Cascader 级联选择

从具有层级关系的数据中选择完整路径，支持多选、搜索和异步加载。浮层选择器与 `CascaderPanel` 共用值、字段映射和勾选规则。

```ts
import { Cascader, CascaderPanel } from '@apollo-design/ui';
import type { CascaderOutputValue } from '@apollo-design/ui';
```


## Props

`ValueCell = (string | number)[]`。单选输出 `ValueCell`，多选输出 `ValueCell[]`；清除时均输出 `[]`，`change` 的 options 同步输出 `[]`。数字 `0`、字符串 `'0'` 和包含分隔符的字符串是不同的合法值。找不到的受控路径仍展示原值，后续补上 options 即使用当前标签。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| options | 数据源；每层 value 在同级中唯一 | BaseOptionType[] | [] |
| value / defaultValue | 当前值 / 非受控初始值；标量按单段路径处理 | CascaderValue | - |
| multiple / checkable | 多选；仅 `checkable: true` 启用多选 | boolean | false |
| fieldNames | label、value、children 字段映射；支持动态更新 | FieldNames | 标准字段名 |
| changeOnSelect | 单选可选择中间层 | boolean | false |
| showCheckedStrategy | 多选输出和标签去重规则，不改变实际勾选传导 | SHOW_PARENT \| SHOW_CHILD | SHOW_PARENT |
| showSearch | 启用搜索；配置 filter、sort、limit、matchInputWidth、autoClearSearchValue | boolean \| CascaderSearchConfig | 单选 false；多选 true |
| searchValue / autoClearSearchValue | 搜索词 / 选择后清空；配置对象中的 autoClearSearchValue 优先 | string / boolean | '' / true |
| loadData | 加载尚无 children 的非叶子路径；同一未完成路径不重复请求。可返回 Promise，拒绝交给 Vue 错误处理器，加载结束后可重试 | (selectedOptions) => void \| Promise&lt;void&gt; | - |
| expandTrigger | 鼠标展开方式；键盘支持方向键、Enter、Escape，多选 Space | 'click' \| 'hover' | 'click' |
| open / defaultOpen | 当前浮层开关 / 非受控初始值 | boolean | false |
| size / disabled / loading / status | 尺寸、禁用、加载提示、表单状态 | SizeType / boolean / boolean / 'error' \| 'warning' | - |
| variant / bordered | outlined、borderless、filled、underlined；未指定 variant 时 bordered 控制旧的边框选择 | SelectVariant / boolean | outlined / true |
| placeholder / notFoundContent | 占位和空内容；同名插槽优先，空插槽不回退 | VNodeChild | - / 'Not Found' |
| allowClear / clearIcon / removeIcon / suffixIcon | 清除、移除和后缀图标 | boolean \| { clearIcon? } / VNodeChild | true |
| expandIcon / loadingIcon | 列展开和异步加载图标；同名作用域插槽优先 | VNodeChild | 方向箭头 / 加载图标 |
| maxTagCount / maxTagTextLength / maxTagPlaceholder | 多选标签数量、文本长度和静态溢出内容；动态内容用插槽 | number / number / VNodeChild | - |
| placement / direction | 浮层位置和文字方向；方向继承当前 ConfigProvider | SelectCommonPlacement / 'ltr' \| 'rtl' | bottomLeft / 'ltr' |
| popupClassName / dropdownClassName | 浮层 class；前者优先 | string | - |
| popupStyle / popupMenuColumnStyle | 浮层根 / 每个菜单列 ul 的样式 | CSSProperties | - |
| popupMatchSelectWidth | 浮层匹配触发器宽度 | boolean \| number | false |
| getPopupContainer | 浮层容器；未指定时继承当前 ConfigProvider | (node) => HTMLElement | - |
| classNames / styles | 语义目标对象，或 `({ props }) => 对象` | CascaderSemanticClassNames / CascaderSemanticStyles | - |
| id / prefixCls | 输入 ID / 组件前缀 | string | 自动 ID / apollo-cascader |

原生 `class`、`style` 与其他 attrs 落到实际触发器；`aria-label`、`aria-labelledby` 落到输入框。语义目标为 root、prefix、suffix、input、placeholder、content、item、itemContent、itemRemove、clear 及 popup.root/list/listItem。Provider 配置、语义样式、原生根样式依次合并，原生根样式优先。

## Slots

插槽内容遵守 Vue 的完整 VNodeChild 语义，支持文本、零值、多个节点和条件插槽。

| 插槽 | 作用域 | 用途 |
| --- | --- | --- |
| default | - | 自定义完整触发器内容 |
| displayRender | { labels, selectedOptions } | 选中路径标签；默认单选以 ` / ` 连接，多选显示末段 |
| optionRender | { option, pathOptions } | 普通菜单选项内容 |
| searchRender | { inputValue, pathOptions, fieldNames } | 搜索命中路径内容 |
| popupRender | { menu: VNode } | 包装原生菜单；用 `<component :is="menu" />` 渲染，保留面板身份与原有事件 |
| expandIcon / loadingIcon | { option } | 每个选项的展开 / 加载图标 |
| suffixIcon / searchIcon | { focused, open, searchValue, showSearch, loading } | 后缀 / 聚焦搜索图标 |
| maxTagPlaceholder | { omittedValues: { value: ValueCell, label, disabled? }[] } | 多选溢出标签内容 |
| placeholder / notFoundContent / clearIcon / removeIcon | - | 对应内容 |

## Emits 与 v-model

| 事件 | 参数 |
| --- | --- |
| update:value | value: CascaderOutputValue |
| change | value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions |
| update:open / openChange | open: boolean |
| update:searchValue / search | text: string |
| focus / blur | FocusEvent |
| clear | 无 |
| popupScroll | Event |
| keydown / keyup / mousedown | 对应原生事件 |

使用 `v-model:value`、`v-model:open`、`v-model:searchValue`；受控时仅提出更新，父级未接收不改变已接受值。传入 `undefined` 撤控时沿用最后实际收到的值。公开通知由 Vue Emits 派发，支持 Vue 原生监听器数组，不再手工调用 attrs 中的回调。

## Ref 与 Panel

组件 ref 提供 `nativeElement: HTMLElement | null` 属性、`focus(options?: FocusOptions)`、`blur()`。

`CascaderPanel`（或 `Cascader.Panel`）只有菜单列，无浮层和输入框。支持 options、value/defaultValue、multiple、fieldNames、changeOnSelect、showCheckedStrategy、loadData、expandTrigger、expandIcon、loadingIcon、direction、disabled、notFoundContent、popupMenuColumnStyle、classNames/styles；支持 `update:value`、`change` 及 optionRender/searchRender/expandIcon/loadingIcon/notFoundContent 插槽。原生 attrs 直接落在可聚焦面板根，键盘交互与浮层一致。

静态属性 `Cascader.SHOW_PARENT` / `Cascader.SHOW_CHILD` 提供策略常量。内部别名 `_InternalPanelDoNotUseOrYouWillBeFired` 仍指向 Panel（历史边界 D113）。

## 开发期迁移与主题

移除函数 Props `displayRender`、`optionRender`、`popupRender`，改用同名作用域插槽；`showSearch.render` 改为 `#searchRender`，嵌套 searchValue/onSearch 改为顶层模型与 `@search`。函数式 maxTagPlaceholder 改为插槽，图标函数改为插槽。无效的 trigger、placeholder2 和重复的 popupVisibleChange/dropdownVisibleChange 通知不再作为公共接口。

8 个组件 Token：controlWidth(184)、controlItemWidth(111)、dropdownHeight(180)、optionSelectedBg、optionSelectedFontWeight、optionPadding、menuPadding、optionSelectedColor。当前 Provider 的 Cascader Token 同步作用于触发器、独立浮层和 Panel，Select 组件覆盖不会越过组件职责覆盖 Cascader。


## 基本 (basic)

省市区级联；`onChange` 的第二个参数是选中项的 options 路径。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { Cascader } from '@apollo-design/ui';

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州', children: [{ value: 'xihu', label: '西湖' }] },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      { value: 'nanjing', label: '南京', children: [{ value: 'zhonghuamen', label: '中华门' }] },
    ],
  },
];

const onChange = (value: unknown) => console.log(value);
</script>

<template>
  <Cascader :options="options" :on-change="onChange" placeholder="请选择地区" />
</template>
```

## 多选 (multiple)

`multiple` 开启多选；`showCheckedStrategy` 控制回填策略（SHOW_PARENT / SHOW_CHILD）。

### multiple.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 multiple demo
import { Cascader } from '@apollo-design/ui';

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州', children: [{ value: 'xihu', label: '西湖' }] },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  { value: 'jiangsu', label: '江苏', children: [{ value: 'nanjing', label: '南京' }] },
];
</script>

<template>
  <Cascader multiple :options="options" placeholder="请选择（可多选）" />
</template>
```

## 搜索 (search)

`showSearch` 开启路径搜索；命中的叶子以 ` / ` 连接展示，关键词高亮。

### search.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 search demo（showSearch）
import { Cascader } from '@apollo-design/ui';

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州', children: [{ value: 'xihu', label: '西湖' }] },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  { value: 'jiangsu', label: '江苏', children: [{ value: 'nanjing', label: '南京' }] },
];
</script>

<template>
  <Cascader :options="options" show-search placeholder="输入关键字搜索" />
</template>
```

## 选中即返回 (change-on-select)

`changeOnSelect` 让任意层级选择都触发 change（返回当前层级的路径）。

### change-on-select.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 changeOnSelect demo
import { Cascader } from '@apollo-design/ui';

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [{ value: 'hangzhou', label: '杭州' }],
  },
];
</script>

<template>
  <Cascader :options="options" change-on-select placeholder="选中即返回" />
</template>
```

## 纯面板 (panel)

`CascaderPanel`（= `Cascader.Panel`）只渲染级联列本身，常用于自定义容器内。

### panel.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 render-panel demo（CascaderPanel）
import { CascaderPanel } from '@apollo-design/ui';

const options = [
  { value: 'zhejiang', label: '浙江', children: [{ value: 'hangzhou', label: '杭州' }] },
];
</script>

<template>
  <CascaderPanel :options="options" />
</template>
```

## 禁用选项 (disabled-option)

在 `options` 上设置 `disabled: true` 禁用父级或叶子节点；下方文本显示 `change` 事件的值路径。

### disabled-option.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 disabled-option demo
import { Cascader } from '@apollo-design/ui';
import { ref } from 'vue';

const options = [
  {
    value: 'zhejiang',
    label: '浙江（整省禁用）',
    disabled: true,
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      {
        value: 'nanjing',
        label: '南京',
        children: [
          { value: 'zhonghuamen', label: '中华门（禁用）', disabled: true },
          { value: 'xuanwumen', label: '玄武门' },
        ],
      },
      { value: 'suzhou', label: '苏州' },
    ],
  },
];

const selected = ref('尚未选择');

const onChange = (value: unknown) => {
  selected.value = Array.isArray(value) ? value.join(' / ') : String(value ?? '');
};
</script>

<template>
  <Cascader :options="options" placeholder="浙江与中华门不可选" @change="onChange" />
  <p>当前选择：{{ selected }}</p>
</template>
```

## 默认值 (default-value)

`default-value` 传入值路径初始化选中项；点击按钮通过改变 `key` 重新挂载以恢复默认值。

### default-value.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 default-value demo：非受控默认值 + 重新挂载恢复
import { Button, Cascader, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      {
        value: 'hangzhou',
        label: '杭州',
        children: [
          { value: 'xihu', label: '西湖' },
          { value: 'lingyin', label: '灵隐寺' },
        ],
      },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

const resetKey = ref(0);
const selected = ref('浙江 / 杭州 / 西湖');

const onChange = (value: unknown) => {
  selected.value = Array.isArray(value) ? value.join(' / ') : String(value ?? '');
};

const reset = () => {
  resetKey.value += 1;
  selected.value = '浙江 / 杭州 / 西湖';
};
</script>

<template>
  <Space orientation="vertical" size="small">
    <Cascader
      :key="resetKey"
      :options="options"
      :default-value="['zhejiang', 'hangzhou', 'xihu']"
      @change="onChange"
    />
    <Space wrap>
      <Button @click="reset">恢复默认值</Button>
      <span>当前：{{ selected }}</span>
    </Space>
  </Space>
</template>
```

## 自定义渲染 (custom-render)

`#optionRender` 定制下拉选项内容，`#displayRender` 定制选中后的展示文案。

### custom-render.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 custom-render demo：optionRender + displayRender
import { Cascader } from '@apollo-design/ui';

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      {
        value: 'hangzhou',
        label: '杭州',
        children: [
          { value: 'xihu', label: '西湖' },
          { value: 'lingyin', label: '灵隐寺' },
        ],
      },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];
</script>

<template>
  <Cascader
    :options="options"
    placeholder="自定义选项与展示文案"
  >
    <template #displayRender="{ labels }">
      <span style="color: #1677ff; font-weight: 600">{{ labels.join(' → ') }}</span>
    </template>
    <template #optionRender="{ option }">
      <span style="display: inline-flex; align-items: center; gap: 6px">
        <span :style="{ width: '6px', height: '6px', borderRadius: '50%', background: option.disabled ? '#bfbfbf' : '#52c41a' }" />
        {{ option.label }}
      </span>
    </template>
  </Cascader>
  <p>下拉选项带状态圆点，选中后面包屑用「→」连接。</p>
</template>
```

## 自定义字段名 (field-names)

`field-names` 将 `name` / `id` / `items` 映射为 label / value / children，`change` 的第二个参数可读回完整选项路径。

### field-names.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 custom-field-names demo
import type { CascaderFieldNames } from '@apollo-design/ui';
import { Cascader } from '@apollo-design/ui';
import { ref } from 'vue';

const fieldNames: CascaderFieldNames = {
  label: 'name',
  value: 'id',
  children: 'items',
};

const options = [
  {
    id: 1,
    name: '浙江',
    items: [
      {
        id: 11,
        name: '杭州',
        items: [
          { id: 111, name: '西湖' },
          { id: 112, name: '灵隐寺' },
        ],
      },
      { id: 12, name: '宁波' },
    ],
  },
  {
    id: 2,
    name: '江苏',
    items: [{ id: 21, name: '南京' }],
  },
];

const selected = ref('尚未选择');

const onChange = (_value: unknown, selectedOptions: unknown) => {
  const path = Array.isArray(selectedOptions)
    ? (selectedOptions as Array<Record<string, unknown>>)
        .map((option) => String(option.name ?? ''))
        .join(' / ')
    : '';
  selected.value = path || '尚未选择';
};
</script>

<template>
  <Cascader
    :options="options"
    :field-names="fieldNames"
    placeholder="字段名为 name / id / items"
    @change="onChange"
  />
  <p>当前路径：{{ selected }}</p>
</template>
```

## 动态加载 (load-data)

`isLeaf: false` 的节点展开时触发 `load-data`，模拟异步补全 `children` 并显示已加载数量。

### load-data.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 load-data demo：isLeaf: false + loadData 异步补全
import type { CascaderBaseOptionType } from '@apollo-design/ui';
import { Cascader } from '@apollo-design/ui';
import { ref } from 'vue';

const options = ref<CascaderBaseOptionType[]>([
  { value: 'zhejiang', label: '浙江', isLeaf: false },
  { value: 'jiangsu', label: '江苏', isLeaf: false },
  { value: 'guangdong', label: '广东', isLeaf: false },
]);

const loadedCount = ref(0);
const allLoaded = ref(false);

const loadData = (selectedOptions: CascaderBaseOptionType[]) => {
  const target = selectedOptions[selectedOptions.length - 1];
  if (!target) return;
  // 已经加载过就不再重复请求（展开/点击父级都会触发 loadData）
  if (Array.isArray(target.children) && target.children.length > 0) return;
  const label = String(target.label ?? '');
  target.loading = true;
  setTimeout(() => {
    target.loading = false;
    target.children = [
      { value: `${String(target.value)}-city-1`, label: `${label}城市一`, isLeaf: true },
      { value: `${String(target.value)}-city-2`, label: `${label}城市二`, isLeaf: true },
    ];
    options.value = [...options.value];
    loadedCount.value += 1;
    allLoaded.value = options.value.every(
      (option) => Array.isArray(option.children) && option.children.length > 0,
    );
  }, 600);
};
</script>

<template>
  <Cascader :options="options" :load-data="loadData" placeholder="点击省份动态加载城市" />
  <p>
    已加载 {{ loadedCount }} 个省份的城市{{ allLoaded ? '（全部完成）' : '，继续点击其它省份' }}
  </p>
</template>
```

## 最大标签数 (max-tag-count)

多选下用 `max-tag-count` 限制展示的标签数量，超出部分折叠为「+ N ...」。

### max-tag-count.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 max-tag-count demo
import { Cascader } from '@apollo-design/ui';

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
      { value: 'wenzhou', label: '温州' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      { value: 'nanjing', label: '南京' },
      { value: 'suzhou', label: '苏州' },
    ],
  },
];
</script>

<template>
  <Cascader
    multiple
    :options="options"
    :max-tag-count="2"
    placeholder="最多显示 2 个标签"
    style="width: 100%"
  />
  <p>选中超过 2 项时折叠为「+ N ...」，移除标签后可继续选择。</p>
</template>
```

## 弹出位置 (placement)

用下拉框切换 `placement`，观察浮层在触发器上方/下方、左侧/右侧对齐的差异。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 placement demo
import { Cascader, Select } from '@apollo-design/ui';
import { ref } from 'vue';

type Placement = 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight';

const placement = ref<Placement>('bottomLeft');

const placementOptions = [
  { value: 'bottomLeft', label: 'bottomLeft' },
  { value: 'bottomRight', label: 'bottomRight' },
  { value: 'topLeft', label: 'topLeft' },
  { value: 'topRight', label: 'topRight' },
];

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

const onPlacementChange = (value: unknown) => {
  placement.value = value as Placement;
};
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 16px">
    <span>placement：</span>
    <Select
      :value="placement"
      :options="placementOptions"
      style="width: 160px"
      @change="onPlacementChange"
    />
  </div>
  <Cascader :options="options" :placement="placement" placeholder="切换浮层方位" />
</template>
```

## 尺寸 (size)

`size` 支持 `small` / `middle` / `large`，选择后下方显示当前值路径。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size demo
import { Cascader, Flex } from '@apollo-design/ui';
import { ref } from 'vue';

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

const selected = ref('尚未选择');

const onChange = (value: unknown) => {
  selected.value = Array.isArray(value) ? value.join(' / ') : String(value ?? '');
};
</script>

<template>
  <Flex gap="middle" align="center" wrap>
    <Cascader size="small" :options="options" placeholder="small" @change="onChange" />
    <Cascader size="middle" :options="options" placeholder="middle" @change="onChange" />
    <Cascader size="large" :options="options" placeholder="large" @change="onChange" />
  </Flex>
  <p>当前选择：{{ selected }}</p>
</template>
```

## 状态 (status)

`status` 提供 `error` / `warning` 校验态，`disabled` 禁用整个选择器。

### status.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 status demo：下拉框切换校验态
import { Cascader, Flex, Select } from '@apollo-design/ui';
import { computed, ref } from 'vue';

type Status = 'default' | 'error' | 'warning';

const status = ref<Status>('default');

const statusOptions = [
  { value: 'default', label: 'default（正常）' },
  { value: 'error', label: 'error' },
  { value: 'warning', label: 'warning' },
];

const statusProp = computed(() => (status.value === 'default' ? undefined : status.value));

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

const onStatusChange = (value: unknown) => {
  status.value = value as Status;
};
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 16px">
    <span>status：</span>
    <Select
      :value="status"
      :options="statusOptions"
      style="width: 160px"
      @change="onStatusChange"
    />
  </div>
  <Flex gap="middle" wrap>
    <Cascader :status="statusProp" :options="options" placeholder="受控 status" />
    <Cascader disabled :options="options" placeholder="disabled" />
  </Flex>
  <p>当前状态：{{ status }}；`disabled` 会禁用整个选择器。</p>
</template>
```

## 组件 Token (component-token)

通过 `ConfigProvider.theme.components.Cascader` 同步设置触发器与浮层的当前 Token，调整控件宽度、列宽、下拉高度、选中项配色与内边距；开关可对比默认 Token 与自定义 Token。

### component-token.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 component-token demo。
// 当前Provider Token同步作用于触发器和teleport浮层。
import { Cascader, ConfigProvider, Switch, Tag } from '@apollo-design/ui';
import { ref } from 'vue';
import type { CascaderOutputValue } from '../interface';

const custom = ref(true);
const value = ref<CascaderOutputValue>(['zhejiang', 'hangzhou']);

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
  {
    value: 'guangdong',
    label: '广东',
    children: [{ value: 'shenzhen', label: '深圳' }],
  },
];
</script>

<template>
  <div class="cascader-component-token-demo" :class="{ 'is-custom': custom }">
    <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 16px">
      <Switch v-model:checked="custom" aria-label="启用自定义组件 Token" />
      <span>自定义 Token</span>
      <Tag color="blue">
        {{ custom ? '已覆盖宽度 / 选中态 / 内边距' : '默认 Token' }}
      </Tag>
    </div>

    <ConfigProvider :theme="{ components: { Cascader: custom ? { controlWidth: 260, controlItemWidth: 142, dropdownHeight: 220, optionSelectedBg: '#fff0f6', optionSelectedFontWeight: 700, optionSelectedColor: '#c41d7f', optionPadding: '8px 14px', menuPadding: 8 } : {} } }">
      <Cascader v-model:value="value" :options="options" placeholder="请选择地区" />
    </ConfigProvider>

    <p style="margin-bottom: 0">
      当前选择：{{ value.length ? value.join(' / ') : '尚未选择' }}
    </p>
  </div>
</template>
```

### ../interface.ts

```ts
import type { CSSProperties, VNode, VNodeChild } from 'vue';
import type { SemanticInput } from '../_internal/use-merge-semantic';
import type { SizeType } from '../config-provider/size-context';
import type { SelectCommonPlacement, SelectSlots, SelectVariant } from '../select/interface';
import type { SearchConfig } from './hooks/search';
import type { BaseOptionType, FieldNames, RawValue, ShowCheckedStrategy, ValueCell } from './utils';

export type CascaderValue = RawValue | ValueCell[];
export type CascaderOutputValue = ValueCell | ValueCell[];
export type CascaderSelectedOptions = (BaseOptionType | null)[] | (BaseOptionType | null)[][];
export type CascaderSearchConfig = Omit<SearchConfig, 'render' | 'searchValue' | 'onSearch'>;
export interface CascaderSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: { root?: string; list?: string; listItem?: string };
}
export interface CascaderSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: { root?: CSSProperties; list?: CSSProperties; listItem?: CSSProperties };
}
export interface CascaderPanelProps {
  prefixCls?: string;
  options?: BaseOptionType[];
  value?: CascaderValue;
  defaultValue?: CascaderValue;
  multiple?: boolean;
  fieldNames?: FieldNames;
  changeOnSelect?: boolean;
  showCheckedStrategy?: ShowCheckedStrategy;
  loadData?: (selectedOptions: BaseOptionType[]) => void | Promise<void>;
  expandTrigger?: 'click' | 'hover';
  expandIcon?: VNodeChild;
  loadingIcon?: VNodeChild;
  direction?: 'ltr' | 'rtl';
  notFoundContent?: VNodeChild;
  disabled?: boolean;
  popupMenuColumnStyle?: CSSProperties;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderPanelProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderPanelProps>;
  'onUpdate:value'?: (value: CascaderOutputValue) => void;
  onChange?: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
}
export interface CascaderProps extends Omit<CascaderPanelProps, 'classNames' | 'styles'> {
  id?: string;
  checkable?: boolean;
  size?: SizeType;
  loading?: boolean;
  variant?: SelectVariant;
  bordered?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild };
  clearIcon?: VNodeChild;
  removeIcon?: VNodeChild;
  suffixIcon?: VNodeChild;
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  showSearch?: boolean | CascaderSearchConfig;
  searchValue?: string;
  autoClearSearchValue?: boolean;
  placeholder?: VNodeChild;
  popupClassName?: string;
  dropdownClassName?: string;
  popupStyle?: CSSProperties;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement;
  status?: 'error' | 'warning';
  maxTagCount?: number;
  maxTagTextLength?: number;
  maxTagPlaceholder?: VNodeChild;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderProps>;
  'onUpdate:open'?: (open: boolean) => void;
  'onUpdate:searchValue'?: (value: string) => void;
  onOpenChange?: (open: boolean) => void;
  onSearch?: (value: string) => void;
  onFocus?: (event: FocusEvent) => void;
  onBlur?: (event: FocusEvent) => void;
  onClear?: () => void;
  onPopupScroll?: (event: Event) => void;
  onKeydown?: (event: KeyboardEvent) => void;
  onKeyup?: (event: KeyboardEvent) => void;
  onMousedown?: (event: MouseEvent) => void;
}
export interface CascaderEmits {
  'update:value': (value: CascaderOutputValue) => void;
  change: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
  'update:open': (open: boolean) => void;
  openChange: (open: boolean) => void;
  'update:searchValue': (value: string) => void;
  search: (value: string) => void;
  focus: (event: FocusEvent) => void;
  blur: (event: FocusEvent) => void;
  clear: () => void;
  popupScroll: (event: Event) => void;
  keydown: (event: KeyboardEvent) => void;
  keyup: (event: KeyboardEvent) => void;
  mousedown: (event: MouseEvent) => void;
}
export interface CascaderOptionSlots {
  optionRender?: (scope: { option: BaseOptionType; pathOptions: BaseOptionType[] }) => VNodeChild;
  searchRender?: (scope: {
    inputValue: string;
    pathOptions: BaseOptionType[];
    fieldNames: FieldNames;
  }) => VNodeChild;
  expandIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
  loadingIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
}
export interface CascaderPanelSlots extends CascaderOptionSlots {
  notFoundContent?: () => VNodeChild;
}
export interface CascaderSlots extends CascaderPanelSlots {
  default?: () => VNodeChild;
  placeholder?: () => VNodeChild;
  displayRender?: (scope: {
    labels: VNodeChild[];
    selectedOptions: (BaseOptionType | null)[];
  }) => VNodeChild;
  suffixIcon?: SelectSlots['suffixIcon'];
  searchIcon?: SelectSlots['suffixIcon'];
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  maxTagPlaceholder?: (scope: {
    omittedValues: { value: ValueCell; label: VNodeChild; disabled?: boolean }[];
  }) => VNodeChild;
  popupRender?: (scope: { menu: VNode }) => VNodeChild;
}
export interface CascaderRef {
  readonly nativeElement: HTMLElement | null;
  focus: (options?: FocusOptions) => void;
  blur: () => void;
}
```

### ../../_internal/use-merge-semantic.ts

````ts
/**
 * 语义化 `classNames` / `styles` 的合并。
 *
 * 契约来源：antd 6.6.4 的 `es/_util/hooks/useMergeSemantic/index.js`（**逐条对齐**）。
 *
 * 为什么单独抽出来：72 个组件里有 60 多个都有 `classNames` / `styles`，合并语义
 * 一旦不一致，就会出现「Button 的覆盖优先级和 Empty 不一样」这类只有用户才会发现的问题。
 * 所以合并规则集中在这里，组件只声明「合并哪些来源、按什么顺序」。
 *
 * ── 与 antd 的对应关系（合并顺序是契约，不能改）────────────────────────────────
 *
 * ```
 * // antd（Empty）
 * const [mergedClassNames, mergedStyles] = useMergeSemantic(
 *   [contextClassNames, classNames],                          // classNamesList
 *   [contextStyles, contextStyleRoot, styles, styleRoot],     // stylesList
 *   { props },
 * );
 * ```
 *
 * 其中 `contextStyleRoot = useSemanticRootStyle(contextStyle)`、`styleRoot = useSemanticRootStyle(style)`，
 * 即把 `style` 这个平铺的 prop 包成 `{ root: style }` 再进合并。
 *
 * 三条必须逐字保留的判据：
 *   1. **classNames 是「拼接」不是「覆盖」** —— `clsx(acc[key], curVal)`，同名键会连起来。
 *   2. **styles 是「逐键浅合并、后者胜」** —— 与 classNames 不同，这里不是拼接。
 *   3. **`style` prop 排在 `styles.root` 之后** —— 所以 `style` 会**覆盖** `styles.root`。
 *      这条最反直觉，也最容易被「顺手改成更合理的顺序」。
 *
 * ── 函数式变体（裁决 `empty-semantic-fn` = B：支持）───────────────────────────
 *
 * antd 允许传 `(info: { props }) => 对象`。我们在 `resolveSemantic` 里逐字对应：
 * 判据是 `isFunction(value) ? value(info) : value`，**没有**额外的「只在需要时求值」优化
 * —— 那种优化会让函数式与对象式的行为出现差异。
 *
 * ── `schema`（嵌套语义槽）—— **2026-10-03 补齐** ──────────────────────────────
 *
 * antd 的第四参 `schema` 用 `_default` 把「字符串形态的嵌套键」落到指定子槽
 * （`classNames.popup = 'x'` ≡ `classNames.popup = { root: 'x' }`），并在最后用
 * `fillObjectBySchema` 保证嵌套键**恒为对象**。
 *
 * 本仓此前没有它，用「只要有一侧是对象就递归」绕过 —— 那在**字符串与对象混用**时
 * 会产垃圾键（`Object.keys('x')`）。antd 6.6.4 里 **9 个组件**传了 schema
 * （`select` / `cascader` / `color-picker` / `menu` / `tabs` / `image` / `splitter` /
 * `input.Search` / `table`），Table 是第一个**真的需要**它的（`body.cell` / `header.cell`）。
 *
 * ⚠️ **两条语义并存、不能合并**：不给 schema 时保持本仓既有行为（7 个消费者钉住它），
 *    给了 schema 才走 antd 的 `mergeClassNamesBySchema`。
 *    判据见 `__tests__/use-merge-semantic.test.ts` 的「反向哨兵」那一条。
 *
 * ── 这个模块没有证明什么 ──────────────────────────────────────────────────────
 *   - 没证明各组件的**合并顺序声明**是对的。本模块只保证「给定顺序，合并结果正确」；
 *     顺序本身由各组件的 compat 用例与 antd 对照（Empty 见 `__tests__/semantic.test.ts`）。
 *   - 没证明**所有该传 schema 的组件都传了**。schema 档 2026-10-03 实现，
 *     select / cascader / color-picker / tabs / image（×2）/ splitter 已补第四参；
 *     menu 无语义通道、`input.Search` 未实现（见 `docs/KNOWN-ISSUES.md` §2 留痕）。
 *
 *   ⚠️ 无 schema 的宽松路径（`mergeClassNames`）**仍在服务既有消费者**：它在
 *     「字符串 + 对象混用」时会产垃圾键（`Object.keys('x')`）。这条**曾**登记在
 *     `docs/KNOWN-ISSUES.md`，该文件的 §1 已于 2026-10-07 清零、登记项转入 §2 的
 *     「已修 / 已裁决」；但宽松路径本身**未改**（7 个既有消费者的用例钉住它）。
 *     若将来统一到 schema 档，需同步改这 7 处并重跑它们的 L4/L6。
 */

import { isFunction } from '@apollo-design/utils';
import {
  type ComputedRef,
  type CSSProperties,
  computed,
  type MaybeRefOrGetter,
  toValue,
} from 'vue';

/** 函数式语义化拿到的上下文。与 antd 的 `{ props }` 同构。 */
export interface SemanticInfo<P> {
  props: P;
}

/** 对象式或函数式的语义化输入。 */
export type SemanticInput<T, P> = T | ((info: SemanticInfo<P>) => T | undefined);

/** 任意可响应化的输入。普通值、ref、getter 都接受（与 `toValue` 同构）。 */
export type MaybeSource<T> = MaybeRefOrGetter<T>;

/**
 * ⚠️ **刻意不用** `_internal/clsx.ts` 那一份（2026-10-07 核对过）。
 *
 * 这里是**更窄**的语义：只保留字符串，数字 / 数组 / 对象一律丢弃。
 * 而共享层那份会展开数组与对象（`{a:true}` → `'a'`）。语义化 `classNames` 的槽位值
 * 本来就是字符串，宽版本在这里只会把「传错了形态」静默变成一个类名。
 * ⇒ 别为了「消重」把它换成共享版 —— 那份窄语义是有意的。
 */
function clsx(...values: unknown[]): string {
  return values.filter((v) => typeof v === 'string' && v !== '').join(' ');
}

/**
 * 求值一个语义化输入。
 *
 * 与 antd 的 `resolveStyleOrClass(value, info)` 逐字对应 —— 包括
 * **只在 `isFunction` 时求值**这一点：传 `null` / `undefined` 会原样返回，
 * 由下游的 `filter(Boolean)` 丢掉。
 */
export function resolveSemantic<T, P>(
  value: SemanticInput<T, P> | undefined | null,
  info: SemanticInfo<P>,
): T | undefined {
  if (value === undefined || value === null) return undefined;
  return isFunction(value) ? (value as (i: SemanticInfo<P>) => T | undefined)(info) : value;
}

/**
 * 合并 classNames。**拼接**语义：同名键连起来，不覆盖。
 *
 * 与 antd 的 `mergeClassNames(schema, ...classNames)` 在 `schema === undefined` 时等价。
 *
 * ⚠️ 实现里有一次类型断言（`as Record<string, string | undefined>`）。
 *    它**不是**类型漏洞，而是「语义键集合由调用方的泛型决定」这一事实的必然结果：
 *    函数体只做键的遍历与字符串拼接，不认识任何具体键。用 `as any` 才是漏洞，
 *    这里断言到的是精确的中间形态。
 */
export function mergeClassNames<CN extends object>(
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const cur = record[key];
      const prev = acc[key];
      // 嵌套语义对象（如 Select 的 classNames.popup.{root,list,listItem}）递归合并；
      // 叶子值按 clsx 拼接（select 期 AutoComplete 抓出：浅合并在 popup 上丢数据）
      if (isPlainRecord(cur) || isPlainRecord(prev)) {
        acc[key] = mergeClassNames((prev ?? {}) as never, (cur ?? {}) as never);
      } else {
        acc[key] = clsx(prev as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

function isPlainRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// ---------------------------------------------------------------------------
// schema（嵌套语义槽）—— antd `useMergeSemantic` 的第四参
// ---------------------------------------------------------------------------

/**
 * schema 的**键名首字符**集合。
 *
 * 与 antd 的 `ValidChar`（`_util/type.ts:91`）**逐字相同**：**只有小写 a–z**。
 * 这不是「随便写的」—— 它正是让 `_default`（下划线开头）**不落进**索引签名、
 * 从而不与 `{ _default?: string }` 冲突的机制。
 * ⇒ 别「顺手」把大写或下划线加进来（会让 `SemanticSchema` 立刻变成 `never` 交叉）。
 */
type LowerChar =
  | 'a'
  | 'b'
  | 'c'
  | 'd'
  | 'e'
  | 'f'
  | 'g'
  | 'h'
  | 'i'
  | 'j'
  | 'k'
  | 'l'
  | 'm'
  | 'n'
  | 'o'
  | 'p'
  | 'q'
  | 'r'
  | 's'
  | 't'
  | 'u'
  | 'v'
  | 'w'
  | 'x'
  | 'y'
  | 'z';

/**
 * 嵌套语义槽的映射表。与 antd 的 `SemanticSchema` 同构。
 *
 * `_default: 'root'` 的语义（**逐条来自 antd 的 `mergeClassNames`**）：
 *   - 该键收到**普通对象** ⇒ 递归按子 schema 合并；
 *   - 该键收到**非对象**（字符串）⇒ 落到 `acc[key][_default]`（即 `classNames.popup = 'x'`
 *     ≡ `classNames.popup = { root: 'x' }`）；
 *   - **没有** `_default` 的子 schema（如 `image` 的 `placeholder: {}`）⇒ 只保证该键
 *     恒为对象（`fillObjectBySchema` 的 `||= {}`），不做字符串转换。
 */
export type SemanticSchema = { _default?: string } & {
  [key: `${LowerChar}${string}`]: SemanticSchema;
};

/**
 * 按**任意字符串键**读子 schema。
 *
 * ⚠️ 必须走这层 cast：`SemanticSchema` 的索引签名是 `` `${LowerChar}${string}` ``
 *    （antd 的 `ValidChar` 口径，见上面的注释），而 `Object.keys()` 给的是 `string`
 *    ⇒ 直接写 `schema[key]` 会 **TS7053**。这里的 cast 是**诚实的**：运行时 schema 的键
 *    本来就来自调用方写的对象字面量，`Object.keys` 拿到的正是那些键。
 */
function subSchema(schema: SemanticSchema, key: string): SemanticSchema | undefined {
  return (schema as Record<string, SemanticSchema | undefined>)[key];
}

/**
 * 按 schema 补齐对象结构（antd `fillObjectBySchema` 逐字）。
 *
 * 两条判据：
 *   ① `_default` 键 ⇒ `newObj[key] ||= {}`（保证**至少是空对象**，不会残留 `undefined`）；
 *   ② 其余子 schema ⇒ 递归（空 schema `{}` 会让该键变成 `{}`）。
 */
export function fillObjectBySchema(
  obj: Record<string, unknown> | undefined,
  schema: SemanticSchema,
): Record<string, unknown> {
  const newObj: Record<string, unknown> = { ...(obj ?? {}) };
  for (const key of Object.keys(schema)) {
    if (subSchema(schema, key)?._default) {
      newObj[key] ||= {};
    } else {
      newObj[key] = fillObjectBySchema(
        newObj[key] as Record<string, unknown> | undefined,
        subSchema(schema, key) as SemanticSchema,
      );
    }
  }
  return newObj;
}

/**
 * **带 schema** 的 classNames 合并（antd `mergeClassNames(schema, ...classNames)` 逐字）。
 *
 * ⚠️ 与下面**无 schema** 的 `mergeClassNames` 是**两条不同的语义**，不要合并：
 *    - 无 schema：只要有一侧是对象就**递归**（本仓在 select/auto-complete 期加的行为，
 *      比 antd 更宽松，且已被 7 个组件的既有用例钉住）；
 *    - 有 schema：**只有 schema 声明过的键**才特殊处理，其余键一律 `clsx` 平铺（antd 语义）。
 *
 *    两者的差别在「字符串 vs 对象混用」时可见：
 *      `classNames: { popup: 'x' }` 与 `{ popup: { root: 'y' } }` 两个来源
 *      —— schema 版给 `popup.root = 'x y'`（正确）；无 schema 版会把 `'x'` 当对象递归
 *      （`Object.keys('x')` ⇒ 垃圾键）。这正是 antd 需要 `_default` 的原因。
 */
export function mergeClassNamesBySchema<CN extends object>(
  schema: SemanticSchema,
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const keySchema = subSchema(schema, key);
      const cur = record[key];
      if (keySchema) {
        if (isPlainRecord(cur)) {
          acc[key] = mergeClassNamesBySchema(keySchema, (acc[key] ?? {}) as never, cur as never);
        } else {
          const defaultField = keySchema._default;
          if (defaultField) {
            const target = (acc[key] ?? {}) as Record<string, unknown>;
            target[defaultField] = clsx(
              target[defaultField] as string | undefined,
              cur as string | undefined,
            );
            acc[key] = target;
          }
        }
      } else {
        acc[key] = clsx(acc[key] as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

/**
 * 合并 styles。**逐键浅合并、后者胜** —— 注意与 classNames 的语义不同。
 *
 * 与 antd 的 `mergeStyles(...styles)` 等价。断言理由同 `mergeClassNames`。
 */
export function mergeStyles<ST extends object>(
  ...sources: readonly (Partial<ST> | undefined)[]
): Partial<ST> {
  const acc: Record<string, CSSProperties | undefined> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, CSSProperties | string | undefined>;
    for (const key of Object.keys(record)) {
      // 🚨 **叶子可能是 CSS 字符串**（Vue 的 `style` attr 允许字符串，而 `attrs.style`
      //    会经 `semanticRootStyle` 进到这里）。直接展开字符串会得到
      //    `{ 0: 'w', 1: 'i', … }` ⇒ Vue 的 `setStyle` 抛
      //    `'set' on proxy: trap returned falsish for property '0'`。
      acc[key] = { ...acc[key], ...normalizeStyleValue(record[key]) };
    }
  }
  return acc as Partial<ST>;
}

/**
 * `'width: 240px; color: red'` → `{ width: '240px', color: 'red' }`。
 *
 * ⚠️ 不引入 `@vue/shared` 的 `parseStringStyle`：它是 `vue` 的**传递依赖**，
 *    直接 import 属于幻影依赖（R7 的精神）。这里只需要支持 `;` 分隔的声明段，
 *    与 Vue 自己的实现判据一致（空段 / 无冒号的段跳过）。
 */
function parseStyleString(text: string): CSSProperties {
  const out: Record<string, string> = {};
  for (const part of text.split(';')) {
    const index = part.indexOf(':');
    if (index < 0) continue;
    const name = part.slice(0, index).trim();
    if (!name) continue;
    out[name] = part.slice(index + 1).trim();
  }
  return out as CSSProperties;
}

/** 样式叶子归一：字符串解析成对象，其余原样。 */
function normalizeStyleValue(value: CSSProperties | string | undefined): CSSProperties | undefined {
  if (typeof value === 'string') {
    return parseStyleString(value);
  }
  return value;
}

/**
 * 把平铺的 `style` 包成 `{ root: style }`。
 *
 * 与 antd 的 `useSemanticRootStyle(style, key = 'root')` 等价 —— 包括
 * 「`style` 为空时返回 `undefined` 而不是 `{ root: undefined }`」这一点：
 * 后者会让 `mergeStyles` 多产出一个 `root` 键，进而在 DOM 上多出一个空的 `style=""`。
 */
export function semanticRootStyle(
  style: CSSProperties | string | undefined,
  key = 'root',
): Record<string, CSSProperties> | undefined {
  if (!style) {
    return undefined;
  }
  // 🚨 `style` 可能是 **CSS 字符串**（`<Input style="width: 240px" />` —— Vue 的 `style`
  //    attr 两种形态都合法）。必须在这里解析成对象，否则下游 `mergeStyles` 的
  //    对象展开会把它拆成 `{ 0: 'w', … }`（Issue #7.1 实测）。
  return { [key]: typeof style === 'string' ? parseStyleString(style) : style };
}

/**
 * 把「可能为空的样式」转成可以直接 `v-bind` 的属性对象。
 *
 * 空样式返回 `{}`（**连 `style` 这个键都没有**），非空返回 `{ style }`。
 *
 * ── 为什么必须做这一步（2026-09-18，empty 实测）──────────────────────────────
 *
 * `mergeStyles()` 的返回值**恒**是对象（可能是 `{}`）。直接绑 `:style` 时：
 *
 * | 渲染路径 | 结果 |
 * |---|---|
 * | 客户端 | `patchStyle` 会把空样式移除 —— 没有 `style` 属性 ✓ |
 * | **SSR** | `ssrRenderAttrs` 对 `style` 键是**无条件**输出的 ⇒ 渲染出 `style=""` ✗ |
 *
 * React（antd）在样式为空时**不输出该属性**。所以 SSR 产物会与上游有差异，
 * 而且每个元素多 9 字节 —— 72 个组件 × 多层结构累积起来是可观的体积。
 *
 * 实测：Empty 一层就有 3 个元素带 `style=""`；改成 `v-bind="styleAttrs(x)"` 后归零。
 *
 * ⚠️ 这个差异 L4 **测不出来** —— 投影会把「没有 style 属性」与 `style=""`
 *    都归一化成空串（`(node.style ?? []).join(';')` 两边都是 `''`）。
 *    它是被渲染 SSR 预览页时肉眼发现的，所以既有 L1 断言也有这里。
 *
 * ⚠️ 所有用 `useMergeSemantic` 的组件都应该这样绑样式，而不是 `:style="mergedStyles.x"`。
 */
export function styleAttrs(style: CSSProperties | undefined): { style?: CSSProperties } {
  if (!style) return {};
  const record = style as Record<string, unknown>;
  for (const key of Object.keys(record)) {
    if (record[key] !== undefined) return { style };
  }
  return {};
}

export interface UseMergeSemanticResult<CN extends object, ST extends object> {
  classNames: ComputedRef<Partial<CN>>;
  styles: ComputedRef<Partial<ST>>;
}

/**
 * 响应式版本的 `useMergeSemantic`。
 *
 * 与 antd 的差别只有一处、且是平台差异（PLATFORM）：antd 每次渲染都重跑一遍合并，
 * 我们用 `computed` 缓存 —— 语义相同，但**依赖必须可追踪**，所以来源要用
 * `() => value` 的形式传，而不是先取值再传。
 *
 * @param classNamesSources 按优先级从低到高排列（后者拼接在前者之后）
 * @param stylesSources 按优先级从低到高排列（后者覆盖前者）
 * @param props 传给函数式变体的 `info.props`。**可以是 getter / ref** ——
 *   函数式变体每次重算都要看到**当前** props。传 `mergedProps.value` 那种
 *   setup 期快照会让 `disabled` / `size` / `variant` 变化后函数式仍按旧值计算
 *   （Issue #3.2）。裸对象仍然可用（`toValue` 原样返回）。
 * @param schema **嵌套语义槽**的映射表（antd 第四参）。给了它就会：
 *   ① classNames 走 `mergeClassNamesBySchema`（`_default` 的字符串→对象转换）；
 *   ② 两个结果都过一遍 `fillObjectBySchema`（保证嵌套键恒为对象）。
 *   ⚠️ 不给时**保持本仓既有行为**（无 schema 的递归合并）—— 7 个既有消费者不受影响。
 */
export function useMergeSemantic<P extends object, CN extends object, ST extends object>(
  classNamesSources: readonly MaybeSource<SemanticInput<Partial<CN>, P> | undefined>[],
  stylesSources: readonly MaybeSource<SemanticInput<Partial<ST>, P> | undefined>[],
  props: MaybeRefOrGetter<P>,
  schema?: SemanticSchema,
): UseMergeSemanticResult<CN, ST> {
  // ⚠️ `info` 必须在**每次重算时**新建，且 `props` 要在 computed 内 `toValue` ——
  //    在 setup 期建一次会把首帧的 props 快照焊死（Issue #3.2）。
  const classNames = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = classNamesSources.map((source) =>
      resolveSemantic<Partial<CN>, P>(toValue(source), info),
    );
    const merged = schema
      ? mergeClassNamesBySchema<CN>(schema, ...resolved)
      : mergeClassNames<CN>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<CN>;
  });

  const styles = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = stylesSources.map((source) =>
      resolveSemantic<Partial<ST>, P>(toValue(source), info),
    );
    const merged = mergeStyles<ST>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<ST>;
  });

  return { classNames, styles };
}
````

### ../../config-provider/size-context.ts

````ts
/**
 * `SizeContext` —— 组件尺寸。
 *
 * 契约来源：antd 6.6.4 的 `es/config-provider/SizeContext.tsx` + `hooks/useSize.ts`。
 *
 * ── 为什么它是**独立 context** 而不是 ConfigContext 的一个字段 ──────────────────
 *
 * antd 把它拆出去是为了「`componentSize` 变化时只重渲染读尺寸的组件」。
 * 本项目的理由更硬：`ConfigContextValue` 是**一个**响应式对象，任何字段变化都会
 * 触发所有读它的 `computed` 重算；而尺寸是被最多组件读的字段之一，独立出来能明显
 * 收窄依赖面。形态上也与 antd 对齐（便于迁移）。
 */

import { type ComputedRef, computed, type InjectionKey, inject } from 'vue';

/**
 * 尺寸。
 *
 * ⚠️ `'medium'` 与 `'middle'` **两个都要**：antd 6 起 `'medium'` 是推荐写法，
 * `'middle'` 仍是默认值且未移除（上游注释：`middle is deprecated and will be removed
 * in v7`）。`COMPONENT-RULES.md` §4 要求枚举值与 antd 一致 ⇒ 不裁剪成 `'medium'`。
 */
export type SizeType = 'small' | 'medium' | 'middle' | 'large';

/**
 * 注入键。
 *
 * 值是 `ComputedRef` 而不是裸值 —— 这样 `useSize` 在 `computed` 里读 `.value`
 * 会被追踪，`componentSize` 变化能传导到下游（对齐 antd 的 context 更新）。
 */
export const sizeContextKey: InjectionKey<ComputedRef<SizeType | undefined>> =
  Symbol('apolloSizeContext');

/**
 * 读取组件尺寸，与自己的 prop 合并。与 antd 的 `useSize` 逐字对应。
 *
 * 四条判据（逐条来自 `hooks/useSize.ts`）：
 *   1. `!customSize` ⇒ 用 context（⚠️ 真值判据：`0` / `''` 也走这一支）。
 *   2. `customSize` 是字符串 ⇒ `customSize ?? size`（字符串恒真，等价于直接返回）。
 *   3. `customSize` 是函数 ⇒ `customSize(size)`。
 *   4. 其余（数字 / 对象）⇒ 用 context。
 *
 * @example
 * ```ts
 * const mergedSize = useSize(props.size);   // ComputedRef<SizeType | undefined>
 * ```
 */
export function useSize<T extends string | number | undefined | object>(
  customSize?: T | ((ctxSize: SizeType | undefined) => T),
): ComputedRef<T | SizeType | undefined> {
  const injected = inject(sizeContextKey, undefined);

  return computed(() => {
    const ctxSize = injected?.value;

    if (!customSize) return ctxSize;

    if (typeof customSize === 'string') return customSize ?? ctxSize;

    if (typeof customSize === 'function') {
      return (customSize as (ctxSize: SizeType | undefined) => T)(ctxSize);
    }

    return ctxSize;
  });
}
````

### ../../select/interface.ts

```ts
/** Public Vue contracts for Select and its option data. */

import type { CSSProperties, VNodeChild } from 'vue';
import type { SizeType } from '../config-provider/size-context';

// ---------------------------------------------------------------------------
// 基础值类型
// ---------------------------------------------------------------------------

export type RawValueType = string | number;

/** antd 的 `SelectValue`。 */
export type SelectValue =
  | RawValueType
  | RawValueType[]
  | LabeledValue
  | LabeledValue[]
  | null
  | undefined;

/** antd 的 `LabeledValue`（labelInValue 的输出形态）。 */
export interface LabeledValue {
  key?: RawValueType;
  value: RawValueType;
  label?: unknown;
}

/** rc 的内部形态（`labelInValue` 的中间表示）。 */
export interface LabelInValueType {
  label?: unknown;
  value: RawValueType;
  key?: RawValueType;
  disabled?: boolean;
  title?: string;
}

export interface BaseOptionType {
  disabled?: boolean;
  className?: string;
  style?: CSSProperties;
  title?: string;
  [name: string]: unknown;
}

export interface DefaultOptionType extends BaseOptionType {
  label?: unknown;
  value?: RawValueType | null;
  children?: Omit<DefaultOptionType, 'children'>[];
  options?: DefaultOptionType[];
}

export type SelectOptionType = BaseOptionType | DefaultOptionType;

/** antd `OptionProps`（`Select.Option` / `Select.OptGroup`，deprecated 但保留）。 */
export interface OptionProps extends BaseOptionType {
  value?: RawValueType | null;
  children?: unknown;
}

export interface OptGroupProps extends BaseOptionType {
  label?: unknown;
  children?: unknown;
}

// ---------------------------------------------------------------------------
// 模式 / 尺寸 / 状态
// ---------------------------------------------------------------------------

/**
 * 公开模式只有 `multiple` / `tags` —— antd 把 `mode="combobox"` 吞成单选
 * （`index.tsx` 的 `mode` memo），只有 `SECRET_COMBOBOX_MODE_DO_NOT_USE` 才真走
 * combobox（AutoComplete 用）。内核实现 combobox 分支，公开类型不声明。
 */
export type SelectMode = 'multiple' | 'tags';

/** 内核模式（engine 内部用）。 */
export type InternalSelectMode = SelectMode | 'combobox';

/**
 * 尺寸。**直接别名到 `config-provider` 的 `SizeType`**（`'small' | 'medium' | 'middle' | 'large'`）。
 *
 * 上游 `SelectProps.size` 就是 `SizeType`；此前手抄成 `'small' | 'middle' | 'large'`
 * 漏了 `medium`（运行时 `useSize` 是吃 `SizeType` 的 ⇒ 类型比运行时窄，Issue #4.3）。
 */
export type SelectSize = SizeType;

export type SelectVariant = 'outlined' | 'borderless' | 'filled' | 'underlined';

export type SelectStatus = 'error' | 'warning' | 'success' | 'validating';

/** antd `SelectCommonPlacement`（`_util/motion.ts` 的 4 值）。 */
export type SelectCommonPlacement = 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight';

export type SelectDirection = 'ltr' | 'rtl';

// ---------------------------------------------------------------------------
// 搜索配置
// ---------------------------------------------------------------------------

export type FilterFunc<OptionType> = (inputValue: string, option: OptionType) => boolean;

export interface SearchConfig<OptionType = DefaultOptionType> {
  autoClearSearchValue?: boolean;
  filterOption?: boolean | FilterFunc<OptionType>;
  filterSort?: (optionA: OptionType, optionB: OptionType, info: { searchValue: string }) => number;
  optionFilterProp?: string | string[];
}

export type SelectSearchConfig = SearchConfig<DefaultOptionType>;

// ---------------------------------------------------------------------------
// 语义槽（classNames / styles）
// ---------------------------------------------------------------------------

export interface SelectSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: {
    root?: string;
    listItem?: string;
    list?: string;
  };
}

export interface SelectSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: {
    root?: CSSProperties;
    listItem?: CSSProperties;
    list?: CSSProperties;
  };
}

export interface FieldNames {
  value?: string;
  label?: string;
  groupLabel?: string;
  options?: string;
}

// ---------------------------------------------------------------------------
// Engine content function types; public component content uses slots.
// ---------------------------------------------------------------------------

/** `FlattenOptionData`（rc `interface.d.ts`）。 */
export interface FlattenOptionData<OptionType = DefaultOptionType> {
  label?: unknown;
  data: OptionType;
  key: string | number;
  value?: RawValueType;
  groupOption?: boolean;
  group?: boolean;
}

/** 选择器里一个已选值的展示形态（rc `DisplayValueType`）。 */
export interface DisplayValueType {
  key?: string | number;
  value?: RawValueType;
  label?: unknown;
  title?: unknown;
  disabled?: boolean;
  index?: number;
}

/** `tagRender` 的入参（rc `CustomTagProps`）。 */
export interface CustomTagProps {
  label?: unknown;
  value?: RawValueType;
  disabled: boolean;
  onClose: (event?: MouseEvent) => void;
  closable: boolean;
  isMaxTag: boolean;
  index?: number;
}

export type OptionRenderFn = (
  option: FlattenOptionData<DefaultOptionType>,
  info: { index: number },
) => VNodeChild;

export type LabelRenderFn = (props: LabelInValueType) => VNodeChild;

export type TagRenderFn = (props: CustomTagProps) => VNodeChild;

export type PopupRenderFn = (menu: unknown) => VNodeChild;

export type ScrollToArg =
  | number
  | {
      index?: number;
      align?: 'top' | 'bottom' | 'auto';
      key?: string | number;
    };

// ---------------------------------------------------------------------------
// 实例句柄（antd `RefSelectProps` = rc `BaseSelectRef`）
// ---------------------------------------------------------------------------

export interface SelectRef {
  focus: (options?: FocusOptions) => void;
  blur: () => void;
  scrollTo: (arg?: ScrollToArg) => void;
  nativeElement: HTMLElement | null;
}

// ---------------------------------------------------------------------------
// Props
// ---------------------------------------------------------------------------

export interface SelectProps<ValueType = SelectValue> {
  // ---- 身份 ----
  id?: string;
  prefixCls?: string;
  /** ⚠️ Vue 原生 `class` / `style` 走 attrs（不是 prop）；这里只为类型面留位。 */
  class?: unknown;

  // ---- 值 ----
  value?: ValueType;
  defaultValue?: ValueType;
  /** 输出 `{ label, value }` 而非裸值。 */
  labelInValue?: boolean;
  /** 回填值取 option 的哪个字段（默认 `label`）。 */
  optionLabelProp?: string;
  fieldNames?: FieldNames;

  // ---- 模式 ----
  mode?: SelectMode;

  // ---- 选项 ----
  options?: DefaultOptionType[];
  /** 搜索时列表的最大高度（默认 256）。 */
  listHeight?: number;
  /** 虚拟滚动的估算行高（默认 controlHeight = 32）。 */
  listItemHeight?: number;
  virtual?: boolean;
  /** 键盘上下键是否自动激活第一项（默认 true，combobox 为 false）。 */
  defaultActiveFirstOption?: boolean;
  // ---- 搜索 ----
  showSearch?: boolean | SelectSearchConfig;
  /** Search text; supports v-model:searchValue. */
  searchValue?: string;
  /** @deprecated 用 `showSearch.autoClearSearchValue` */
  autoClearSearchValue?: boolean;
  /** @deprecated 用 `showSearch.filterOption` */
  filterOption?: boolean | FilterFunc<DefaultOptionType>;
  /** @deprecated 用 `showSearch.filterSort` */
  filterSort?: SearchConfig<DefaultOptionType>['filterSort'];
  /** @deprecated 用 `showSearch.optionFilterProp` */
  optionFilterProp?: string | string[];

  // ---- 外观 ----
  size?: SelectSize;
  variant?: SelectVariant;
  /** @deprecated 用 `variant` */
  bordered?: boolean;
  status?: SelectStatus;
  disabled?: boolean;
  loading?: boolean;
  placeholder?: string;
  /** @deprecated 默认显示箭头，隐藏请用空的 `#suffixIcon` 插槽或 `showArrow: false` */
  showArrow?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild; label?: string };
  maxLength?: number;

  // ---- 多选 ----
  maxCount?: number;
  maxTagCount?: number;
  maxTagTextLength?: number;
  tokenSeparators?: string[] | ((input: string) => string[]);

  // ---- 浮层 ----
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  direction?: SelectDirection;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement | ShadowRoot;
  transitionName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  popupClassName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  dropdownClassName?: string;
  /** @deprecated 用 `styles.popup.root` */
  dropdownStyle?: CSSProperties;
  popupStyle?: CSSProperties;

  // ---- 语义槽 ----
  classNames?: SelectSemanticClassNames;
  styles?: SelectSemanticStyles;

  // ---- 无障碍 ----
  tabIndex?: number;
  autoFocus?: boolean;
  title?: string;
  role?: string;
}

// ---------------------------------------------------------------------------
// 事件（Vue 侧：语义事件 + v-model 同发，见 PITFALLS 162）
// ---------------------------------------------------------------------------

export interface SelectEmits<ValueType = SelectValue> {
  change: [value: ValueType, option: DefaultOptionType | DefaultOptionType[] | undefined];
  'update:value': [value: ValueType];
  select: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  deselect: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  search: [value: string];
  'update:searchValue': [value: string];
  openChange: [open: boolean];
  'update:open': [open: boolean];
  focus: [event: FocusEvent];
  blur: [event: FocusEvent];
  clear: [];
  popupScroll: [event: Event];
  inputKeyDown: [event: KeyboardEvent];
}

// ---------------------------------------------------------------------------
// Slots（规则 C8-R2：ReactNode / render prop 一律 slot —— **不**保留同名 prop。
// 文本类 prop（placeholder）保留 string 便捷形态，slot 优先。）
// ---------------------------------------------------------------------------

export interface SelectSlots {
  default?: () => VNodeChild;
  prefix?: () => VNodeChild;
  suffixIcon?: (props: {
    searchValue: string;
    open: boolean;
    focused: boolean;
    showSearch: boolean;
    loading?: boolean;
  }) => VNodeChild;
  searchIcon?: () => VNodeChild;
  loadingIcon?: () => VNodeChild;
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  menuItemSelectedIcon?: (props: {
    value?: unknown;
    disabled?: boolean;
    isSelected?: boolean;
  }) => VNodeChild;
  placeholder?: () => VNodeChild;
  notFoundContent?: () => VNodeChild;
  optionRender?: (props: {
    option: FlattenOptionData<DefaultOptionType>;
    index: number;
  }) => VNodeChild;
  tagRender?: (props: CustomTagProps) => VNodeChild;
  labelRender?: (props: LabelInValueType) => VNodeChild;
  popupRender?: (props: { menu: VNodeChild }) => VNodeChild;
  maxTagPlaceholder?: (props: { omittedValues: DisplayValueType[] }) => VNodeChild;
}
```

### ../hooks/search.ts

```ts
/**
 * Cascader 的搜索 hooks —— `useSearchConfig` / `useSearchOptions` 的 Vue 版。
 *
 * 判据（docs/analysis/cascader.md §3.4）：
 * - `showSearch` 为对象时合入默认配置（`matchInputWidth: true` / `limit: 50`）；
 * - `limit <= 0` 视为 false（不限制）；
 * - 过滤只在**叶子**（或 changeOnSelect / 多选的任意层）上做；命中的结果项用
 *   `render` 产出 label（antd 薄壳会注入带高亮的 render），并挂 `SEARCH_MARK`
 *   保存完整路径（展示与回填都需要它）；
 * - `sort` 提供时覆盖默认顺序。
 */

import { type ComputedRef, computed, type Ref } from 'vue';

import {
  type BaseOptionType,
  type FieldNames,
  type FilledFieldNames,
  fillFieldNames,
  getOptionChildren,
  getOptionLabel,
  getOptionValue,
  getSearchPath,
  SEARCH_MARK,
} from '../utils';

export interface SearchConfig {
  filter?: (
    searchValue: string,
    pathOptions: BaseOptionType[],
    fieldNames: { label: string },
  ) => boolean;
  render?: (
    inputValue: string,
    pathOptions: BaseOptionType[],
    prefixCls: string,
    fieldNames: FieldNames,
  ) => unknown;
  sort?: (
    a: BaseOptionType[],
    b: BaseOptionType[],
    searchValue: string,
    fieldNames: FieldNames,
  ) => number;
  matchInputWidth?: boolean;
  limit?: number | false;
  autoClearSearchValue?: boolean;
}

/** `showSearch` → [是否开启, 配置]（上游 useSearchConfig）。 */
export function normalizeSearchConfig(
  showSearch: boolean | Omit<SearchConfig, 'render'> | undefined,
  props: { autoClearSearchValue?: boolean },
): [boolean, SearchConfig] {
  if (!showSearch) return [false, {}];

  let searchConfig: SearchConfig = {
    matchInputWidth: true,
    limit: 50,
    autoClearSearchValue: props.autoClearSearchValue,
  };
  if (showSearch && typeof showSearch === 'object') {
    const {
      filter,
      sort,
      matchInputWidth = true,
      limit = 50,
      autoClearSearchValue = props.autoClearSearchValue,
    } = showSearch;
    searchConfig = { filter, sort, matchInputWidth, limit, autoClearSearchValue };
  }
  if (typeof searchConfig.limit === 'number' && searchConfig.limit <= 0) {
    searchConfig.limit = false;
  }
  return [true, searchConfig];
}

const defaultFilter = (
  search: string,
  options: BaseOptionType[],
  { label = '' }: { label?: string },
): boolean =>
  options.some((opt) =>
    String(opt[label] ?? '')
      .toLowerCase()
      .includes(search.toLowerCase()),
  );

const defaultRender = (
  _inputValue: string,
  path: BaseOptionType[],
  _prefixCls: string,
  fieldNames: FieldNames,
): unknown => {
  const fields = fillFieldNames(fieldNames);
  const labels = path.map((option) =>
    getOptionLabel(option, fields, getOptionValue(option, fields)),
  );
  return labels.every((label) => typeof label === 'string' || typeof label === 'number')
    ? labels.join(' / ')
    : labels.flatMap((label, index) => (index ? [' / ', label] : [label]));
};

/** 搜索态的候选 options（过滤 + render + limit + sort；上游 useSearchOptions）。 */
export function computeSearchOptions(
  search: string,
  options: BaseOptionType[],
  fieldNames: FilledFieldNames,
  prefixCls: string,
  config: SearchConfig,
  enableHalfPath: boolean,
): BaseOptionType[] {
  const { filter = defaultFilter, render = defaultRender, limit = 50, sort } = config;

  const filteredOptions: BaseOptionType[] = [];
  if (!search) return [];

  function dig(
    list: BaseOptionType[],
    pathOptions: BaseOptionType[],
    parentDisabled = false,
  ): void {
    list.forEach((option) => {
      // 无 sort 且有 limit 时攒够即停（上游的 perf saving）
      if (!sort && limit !== false && limit > 0 && filteredOptions.length >= limit) return;

      const connectedPathOptions = [...pathOptions, option];
      const children = getOptionChildren(option, fieldNames);
      const mergedDisabled = parentDisabled || !!option.disabled;

      // 只在叶子（或 changeOnSelect / 多选的任意层）上做过滤
      if (!children || children.length === 0 || enableHalfPath) {
        if (filter(search, connectedPathOptions, { label: fieldNames.label })) {
          filteredOptions.push({
            ...option,
            disabled: mergedDisabled,
            [fieldNames.label]: render(search, connectedPathOptions, prefixCls, {
              label: fieldNames.label,
              value: fieldNames.value,
              children: fieldNames.children,
            }),
            [SEARCH_MARK]: connectedPathOptions,
            [fieldNames.children]: undefined,
          });
        }
      }
      if (children) {
        dig(children, connectedPathOptions, mergedDisabled);
      }
    });
  }
  dig(options, []);

  if (sort) {
    filteredOptions.sort((a, b) =>
      sort(getSearchPath(a) ?? [], getSearchPath(b) ?? [], search, {
        label: fieldNames.label,
        value: fieldNames.value,
        children: fieldNames.children,
      }),
    );
  }
  return limit !== false && limit > 0 ? filteredOptions.slice(0, limit) : filteredOptions;
}

/** 响应式包装（供组件层使用）。 */
export function useSearchOptions(
  search: Ref<string>,
  options: ComputedRef<BaseOptionType[]>,
  fieldNames: Ref<FilledFieldNames>,
  prefixCls: Ref<string>,
  config: Ref<SearchConfig>,
  enableHalfPath: boolean,
): ComputedRef<BaseOptionType[]> {
  return computed(() =>
    computeSearchOptions(
      search.value,
      options.value,
      fieldNames.value,
      prefixCls.value,
      config.value,
      enableHalfPath,
    ),
  );
}
```

### ../utils.ts

```ts
import { isVNode, type VNodeChild } from 'vue';
import { convertDataToEntities, type DataEntity } from './engine/tree';

/** Internal path keys retain both the value type and path boundaries. */
export const SHOW_PARENT = 'SHOW_PARENT';
export const SHOW_CHILD = 'SHOW_CHILD';
export type ShowCheckedStrategy = typeof SHOW_PARENT | typeof SHOW_CHILD;
export interface FieldNames {
  label?: string;
  value?: string;
  children?: string;
}
export interface FilledFieldNames {
  label: string;
  value: string;
  key: string;
  children: string;
}
export type BaseOptionType = Record<string, unknown> & {
  disabled?: boolean;
  isLeaf?: boolean;
  loading?: boolean;
};
export type DefaultOptionType = BaseOptionType & {
  label?: VNodeChild;
  value?: string | number;
  children?: DefaultOptionType[];
};
export type ValueCell = (string | number)[];
export type RawValue = string | number | ValueCell;

export function toPathKey(value: ValueCell): string {
  return JSON.stringify(value);
}
export function toPathKeys(values: ValueCell[]): string[] {
  return values.map(toPathKey);
}
export function toPathValueStr(pathKey: string): string[] {
  const value: unknown = JSON.parse(pathKey);
  if (!Array.isArray(value) || !value.every(isValue))
    throw new TypeError('[Cascader] Invalid path key');
  return value.map(String);
}
export function fillFieldNames(fieldNames?: FieldNames): FilledFieldNames {
  const { label = 'label', value = 'value', children = 'children' } = fieldNames ?? {};
  return { label, value, key: value, children };
}
export function isValue(value: unknown): value is string | number {
  return typeof value === 'string' || typeof value === 'number';
}
export function getOptionValue(option: BaseOptionType, fields: FilledFieldNames): string | number {
  const value = option[fields.value];
  if (!isValue(value))
    throw new TypeError(`[Cascader] Option ${fields.value} must be a string or number`);
  return value;
}
export function isOption(value: unknown): value is BaseOptionType {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}
export function getOptionChildren(
  option: BaseOptionType | undefined,
  fields: FilledFieldNames,
): BaseOptionType[] {
  const children = option?.[fields.children];
  if (children === undefined || children === null) return [];
  if (!Array.isArray(children) || !children.every(isOption))
    throw new TypeError(`[Cascader] Option ${fields.children} must be an array of options`);
  return children;
}
export function getSearchPath(option: BaseOptionType): BaseOptionType[] | undefined {
  const path = option[SEARCH_MARK];
  return Array.isArray(path) && path.every(isOption) ? path : undefined;
}
export function toContent(value: unknown): VNodeChild {
  if (
    value === undefined ||
    value === null ||
    typeof value === 'string' ||
    typeof value === 'number' ||
    typeof value === 'boolean' ||
    isVNode(value)
  )
    return value;
  if (Array.isArray(value)) return value.map(toContent);
  throw new TypeError('[Cascader] Option labels must be Vue renderable content');
}
export function getOptionLabel(
  option: BaseOptionType | null,
  fields: FilledFieldNames,
  fallback: string | number,
): VNodeChild {
  const label = option?.[fields.label];
  return label === undefined ? fallback : toContent(label);
}
export function isLeaf(option: BaseOptionType | undefined, fields: FilledFieldNames): boolean {
  return option?.isLeaf ?? getOptionChildren(option, fields).length === 0;
}
export function scrollIntoParentView(element: HTMLElement): void {
  const parent = element.parentElement;
  if (!parent) return;
  const offset = element.offsetTop - parent.offsetTop;
  if (offset < parent.scrollTop) parent.scrollTo({ top: offset });
  else if (offset + element.clientHeight > parent.scrollTop + parent.clientHeight)
    parent.scrollTo({ top: offset + element.clientHeight - parent.clientHeight });
}
export const SEARCH_MARK = '__rc_cascader_search_mark__';
export function getFullPathKeys(
  options: BaseOptionType[],
  fields: FilledFieldNames,
): (ValueCell | undefined)[] {
  return options.map((option) =>
    getSearchPath(option)?.map((node) => getOptionValue(node, fields)),
  );
}
function isValueCell(value: unknown): value is ValueCell {
  return Array.isArray(value) && value.every(isValue);
}
export function toRawValues(value: RawValue | RawValue[] | undefined): ValueCell[] {
  if (value === undefined) return [];
  if (isValue(value)) return [[value]];
  if (!value.length) return [];
  if (isValueCell(value)) return [value];
  return value.map((path) => {
    if (!isValueCell(path))
      throw new TypeError('[Cascader] Values must be paths of strings or numbers');
    return path;
  });
}
export function formatStrategyValues(
  pathKeys: string[],
  getEntities: () => Record<string, DataEntity>,
  strategy: ShowCheckedStrategy,
): string[] {
  const checked = new Set(pathKeys);
  const entities = getEntities();
  return pathKeys.filter((key) => {
    const entity = Object.hasOwn(entities, key) ? entities[key] : undefined;
    if (entity?.node.disabled) return true;
    return strategy === SHOW_CHILD
      ? !entity?.children?.some((child) => checked.has(child.key))
      : !(entity?.parent && !entity.parent.node.disabled && checked.has(entity.parent.key));
  });
}
export interface PathOption {
  value: string | number;
  index: number;
  option: BaseOptionType | null;
}
export function toPathOptions(
  path: ValueCell,
  options: BaseOptionType[],
  fields: FilledFieldNames,
  stringMode = false,
): PathOption[] {
  let list = options;
  return path.map((value) => {
    const index = list.findIndex((option) =>
      stringMode ? String(option[fields.value]) === String(value) : option[fields.value] === value,
    );
    const option = list[index] ?? null;
    list = getOptionChildren(option ?? undefined, fields);
    return { value: option ? getOptionValue(option, fields) : value, index, option };
  });
}
export { convertDataToEntities };
```

### ../engine/tree.ts

```ts
/**
 * Cascader 依赖的两棵「树算法」—— `@rc-component/tree` 的 Vue 版移植。
 *
 * ── 为什么在这里，而不是独立包 ──────────────────────────────────────────────
 *
 * `foundation.json` 的开放决策 `early-extract-table-core-tree-core` 结论是
 * **A：不提前抽取独立包，等第二个消费者出现**。Cascader（多选的勾选传导）是第一个
 * 消费者，所以算法先落在 `cascader/engine/`；将来 Tree 组件需要时再按
 * `ActionButton` 那套做法提升到 `_internal/`（原位置留垫片）。
 *
 * ── 两个算法 ────────────────────────────────────────────────────────────────
 *
 * 1. `convertDataToEntities(dataNodes, config)` —— 把嵌套 options 摊成扁平实体表，
 *    并补出 `parent` / `children`（实体层面）与 `level` / `pos` / `nodes`（路径）。
 * 2. `conductCheck(keyList, checked, keyEntities)` —— 勾选传导：
 *    - `checked === true`（fill）：父选中 ⇒ 向下补全所有子；子全选 ⇒ 向上补父；
 *      部分选中 ⇒ 父记 halfChecked。
 *    - `checked === { checked: false, halfCheckedKeys }`（clean）：反向清理。
 *
 * 契约来源：`@rc-component/tree@1.x` 的 `es/utils/treeUtil.js`（convertDataToEntities /
 * traverseDataNodes）与 `es/utils/conductUtil.js`（conductCheck / fill+clean）。
 * 行为逐条对齐，**不复制源码**。
 */

/** 树节点实体。 */
export interface DataEntity {
  /** 原始节点。 */
  node: Record<string, unknown>;
  /** 从根到当前节点的原始节点链（Cascader 用它拼 pathKey）。 */
  nodes: Record<string, unknown>[];
  /** 在同级中的下标。 */
  index: number;
  /** 节点 key（`getKey(key, pos)`：key 缺失时回退 pos）。 */
  key: string;
  /** 位置串（形如 `0-1-2`）。 */
  pos: string;
  /** 层级（根为 0）。 */
  level: number;
  /** 父实体（根为 undefined）。 */
  parent?: DataEntity;
  /** 子实体列表（构造期填充）。 */
  children?: DataEntity[];
}

export interface Wrapper {
  posEntities: Record<string, DataEntity>;
  keyEntities: Record<string, DataEntity>;
  [key: string]: unknown;
}

export interface ConvertConfig {
  /** 用自定义字段解析（Cascader 传 `{ key: value字段, children }`）。 */
  fieldNames?: { key?: string; children?: string };
  /** 包装器扩展（Cascader 用它挂 `pathKeyEntities`）。 */
  initWrapper?: (wrapper: Wrapper) => Wrapper | undefined;
  /** 每个实体构造后的钩子（Cascader 用它把 key 覆写成 pathKey）。 */
  processEntity?: (entity: DataEntity, wrapper: Wrapper) => void;
  /** 全部处理完的钩子。 */
  onProcessFinished?: (wrapper: Wrapper) => void;
}

const DEFAULT_FIELD_NAMES = { key: 'key', children: 'children' };

function getPosition(level: string | number, index: number): string {
  return `${level}-${index}`;
}

function getKey(key: unknown, pos: string): string {
  return key !== null && key !== undefined ? String(key) : pos;
}

/**
 * 遍历嵌套数据（广度优先按层级展开，与上游同序）。
 *
 * ⚠️ 上游 `traverseDataNodes` 的 `nodes` 是**路径链**（根→当前），不是 children ——
 *    Cascader 的 typed value path 依赖完整的 nodes 路径。
 */
export function traverseDataNodes(
  dataNodes: Record<string, unknown>[],
  callback: (item: {
    node: Record<string, unknown>;
    index: number;
    pos: string;
    key: string;
    parentPos: string;
    level: number;
    nodes: Record<string, unknown>[];
  }) => void,
  config: ConvertConfig = {},
): void {
  const { key: fieldKey, children: fieldChildren } = {
    ...DEFAULT_FIELD_NAMES,
    ...(config.fieldNames ?? {}),
  };

  /**
   * @param level 本节点的 level；根调用传 **0** ⇒ 第一层节点的 level 为 0
   *              （rc-tree 的 level 从 0 起算）。⚠️ 不能用 `parentLevel + 1`
   *              的写法——虚拟根会把 -1 加成 0 再传给子，整体偏移一层。
   */
  function processNode(
    node: Record<string, unknown> | null,
    index: number,
    parent: { pos: string; level: number } | null,
    pathNodes: Record<string, unknown>[],
    level: number,
  ): void {
    const mergedParent = parent as { pos: string; level: number } | undefined;
    const children = (node ? node[fieldChildren] : dataNodes) as
      | Record<string, unknown>[]
      | undefined;
    // biome-ignore lint/style/noNonNullAssertion: node 非空时 mergedParent 必由调用方给出（pos/parentPos 都从它派生）
    const pos = node ? getPosition(mergedParent!.pos, index) : '0';
    const connectNodes = node ? [...pathNodes, node] : [];

    if (node) {
      callback({
        node,
        index,
        pos,
        key: getKey(node[fieldKey], pos),
        // biome-ignore lint/style/noNonNullAssertion: 同上 —— 这一支只在 node 非空时执行
        parentPos: mergedParent!.pos,
        level,
        nodes: connectNodes,
      });
    }

    (children ?? []).forEach((child, childIndex) => {
      processNode(child, childIndex, { pos, level }, connectNodes, level + 1);
    });
  }

  // ⚠️ 虚拟根的 level 是 **-1**：递归里 `level + 1` 后第一层节点的 level 才是 0
  //    （rc-tree 的 level 从 0 起算；传 0 会让整棵树偏移一层，conduct 的层级分组全错）
  processNode(null, 0, { pos: '0', level: -1 }, [], -1);
}

/**
 * 摊平嵌套数据为实体表。
 *
 * 与上游同构：同时产出 `posEntities` 与 `keyEntities`，`initWrapper` 可扩展包装器，
 * `processEntity` 在每个实体建好后回调（Cascader 借此把 `entity.key` 覆写成 pathKey）。
 */
export function convertDataToEntities(
  dataNodes: Record<string, unknown>[],
  config: ConvertConfig = {},
): Wrapper {
  const posEntities: Record<string, DataEntity> = {};
  const keyEntities: Record<string, DataEntity> = {};
  let wrapper: Wrapper = { posEntities, keyEntities };
  if (config.initWrapper) {
    wrapper = config.initWrapper(wrapper) ?? wrapper;
  }

  traverseDataNodes(
    dataNodes,
    (item) => {
      const { node, index, pos, key, parentPos, level, nodes } = item;
      const entity: DataEntity = { node, nodes, index, key, pos, level };
      const mergedKey = getKey(key, pos);

      Object.defineProperty(posEntities, pos, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });
      Object.defineProperty(keyEntities, mergedKey, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });

      entity.parent = Object.hasOwn(posEntities, parentPos) ? posEntities[parentPos] : undefined;
      if (entity.parent) {
        entity.parent.children = entity.parent.children || [];
        entity.parent.children.push(entity);
      }

      config.processEntity?.(entity, wrapper);
    },
    config,
  );

  config.onProcessFinished?.(wrapper);
  return wrapper;
}

// ================================ conduct ================================

export interface ConductResult {
  checkedKeys: string[];
  halfCheckedKeys: string[];
}

/** 上游 `isCheckDisabled`：`disabled` / `disableCheckbox` / `checkable === false`。 */
function isCheckDisabled(node: Record<string, unknown> | undefined): boolean {
  if (!node) return false;
  const { disabled, disableCheckbox, checkable } = node as {
    disabled?: boolean;
    disableCheckbox?: boolean;
    checkable?: boolean;
  };
  return !!(disabled || disableCheckbox) || checkable === false;
}

function removeFromCheckedKeys(
  halfCheckedKeys: Set<string>,
  checkedKeys: Set<string>,
): Set<string> {
  const filtered = new Set<string>();
  halfCheckedKeys.forEach((key) => {
    if (!checkedKeys.has(key)) filtered.add(key);
  });
  return filtered;
}

/** 按层级分组（上游 `conductCheck` 的第一步）。 */
function groupByLevel(keyEntities: Record<string, DataEntity>) {
  const levelEntities = new Map<number, Set<DataEntity>>();
  let maxLevel = 0;
  Object.keys(keyEntities).forEach((key) => {
    // noUncheckedIndexedAccess：索引访问可能 undefined（key 来自 Object.keys，防御式收窄）
    const entity = Object.hasOwn(keyEntities, key) ? keyEntities[key] : undefined;
    if (!entity) return;
    const { level } = entity;
    // ⚠️ 用局部变量接住（`get(...)!` 消不掉，且 `Map.get` 的返回类型永远是 `T | undefined`）
    let levelSet = levelEntities.get(level);
    if (!levelSet) {
      levelSet = new Set();
      levelEntities.set(level, levelSet);
    }
    levelSet.add(entity);
    maxLevel = Math.max(maxLevel, level);
  });
  return { levelEntities, maxLevel };
}

/** 自底向上：父的全部（非禁用）子是否都选中 / 部分选中。 */
function conductParent(
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  checkedKeys: Set<string>,
  halfCheckedKeys: Set<string>,
  getDisabled: (node: Record<string, unknown>) => boolean,
  onAllChecked: (parentKey: string) => void,
  onPartialChecked: (parentKey: string) => void,
): void {
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { node } = entity;
      const parent = entity.parent;
      if (!parent || getDisabled(node) || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const checked = checkedKeys.has(key);
          if (allChecked && !checked) allChecked = false;
          if (!partialChecked && (checked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (allChecked) onAllChecked(parent.key);
      if (partialChecked) onPartialChecked(parent.key);
      visitedKeys.add(parent.key);
    });
  }
}

function fillConductCheck(
  keys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  const halfCheckedKeys = new Set<string>();

  // 自顶向下：父选中 ⇒ 补子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (checkedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.add(childEntity.key);
          });
      }
    });
  }

  // 自底向上：子全选 ⇒ 补父；部分 ⇒ half
  conductParent(
    levelEntities,
    maxLevel,
    checkedKeys,
    halfCheckedKeys,
    getDisabled,
    (parentKey) => checkedKeys.add(parentKey),
    (parentKey) => halfCheckedKeys.add(parentKey),
  );

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

function cleanConductCheck(
  keys: Set<string>,
  halfKeys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  let halfCheckedKeys = new Set(halfKeys);

  // 自顶向下：未选中且非半选 ⇒ 清掉子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (!checkedKeys.has(key) && !halfCheckedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.delete(childEntity.key);
          });
      }
    });
  }

  // ⚠️ 自底向上必须**单遍**：`delete(parent.key)` 会立刻影响更高一层的判定
  //    （上游就是同一轮里先算 allChecked / partialChecked 再改 checkedKeys）。
  //    拆成两遍会让高层读到「本该删掉的父」，half 集合偏大。
  halfCheckedKeys = new Set<string>();
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { parent, node } = entity;
      if (getDisabled(node) || !parent || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const isChecked = checkedKeys.has(key);
          if (allChecked && !isChecked) allChecked = false;
          if (!partialChecked && (isChecked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (!allChecked) checkedKeys.delete(parent.key);
      if (partialChecked) halfCheckedKeys.add(parent.key);
      visitedKeys.add(parent.key);
    });
  }

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

/**
 * 勾选传导。
 *
 * @param keyList 当前 key 列表
 * @param checked `true` = fill（补全）；`{ checked: false, halfCheckedKeys }` = clean（清理）
 * @param keyEntities `convertDataToEntities` 产出的 `keyEntities`
 */
export function conductCheck(
  keyList: string[],
  checked: true | { checked: false; halfCheckedKeys: string[] },
  keyEntities: Record<string, DataEntity>,
  getCheckDisabled?: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const getDisabled = getCheckDisabled ?? isCheckDisabled;

  // 只处理存在的 key（上游会 warning 缺失的 key，本仓静默过滤）
  const keys = new Set(keyList.filter((key) => Object.hasOwn(keyEntities, key)));

  const { levelEntities, maxLevel } = groupByLevel(keyEntities);

  if (checked === true) {
    return fillConductCheck(keys, levelEntities, maxLevel, getDisabled);
  }
  return cleanConductCheck(
    keys,
    new Set(checked.halfCheckedKeys),
    levelEntities,
    maxLevel,
    getDisabled,
  );
}
```

## 自定义下拉 (custom-dropdown)

通过 `popupClassName`、`popupStyle` 与 `popupMenuColumnStyle` 定制浮层的圆角、阴影、内边距和列背景；开关可切换默认与自定义样式。

### custom-dropdown.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 custom-dropdown demo：popupClassName + popupStyle
import { Cascader, Switch, Tag } from '@apollo-design/ui';
import type { CSSProperties } from 'vue';
import { computed, ref } from 'vue';
import type { CascaderOutputValue } from '../interface';

const enhanced = ref(true);
const value = ref<CascaderOutputValue>([]);

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

const popupClassName = computed(() =>
  enhanced.value ? 'cascader-custom-dropdown-popup' : undefined,
);

const popupStyle = computed<CSSProperties | undefined>(() =>
  enhanced.value
    ? {
        borderRadius: '14px',
        border: '1px solid #95de64',
        boxShadow: '0 12px 28px rgba(82, 196, 26, 0.18)',
      }
    : undefined,
);

const columnStyle = computed<CSSProperties | undefined>(() =>
  enhanced.value ? { backgroundColor: 'var(--apollo-color-success-bg)' } : undefined,
);

const selectedText = computed(() => (value.value.length ? value.value.join(' / ') : '尚未选择'));
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 16px">
      <Switch v-model:checked="enhanced" aria-label="启用自定义浮层样式" />
      <span>自定义浮层</span>
      <Tag color="green">{{ enhanced ? '圆角 / 阴影 / 列背景' : '默认浮层' }}</Tag>
    </div>

    <Cascader
      v-model:value="value"
      :options="options"
      :popup-class-name="popupClassName"
      :popup-style="popupStyle"
      :popup-menu-column-style="columnStyle"
      placeholder="请选择地区"
    />

    <p style="margin-bottom: 0">当前选择：{{ selectedText }}</p>
  </div>
</template>

<style>
.apollo-cascader-dropdown.cascader-custom-dropdown-popup {
  padding: 8px;
}

.cascader-custom-dropdown-popup .apollo-cascader-menu {
  border-radius: 10px;
}

.cascader-custom-dropdown-popup .apollo-cascader-menu:not(:last-child) {
  border-inline-end-color: #b7eb8f;
}
</style>
```

### ../interface.ts

```ts
import type { CSSProperties, VNode, VNodeChild } from 'vue';
import type { SemanticInput } from '../_internal/use-merge-semantic';
import type { SizeType } from '../config-provider/size-context';
import type { SelectCommonPlacement, SelectSlots, SelectVariant } from '../select/interface';
import type { SearchConfig } from './hooks/search';
import type { BaseOptionType, FieldNames, RawValue, ShowCheckedStrategy, ValueCell } from './utils';

export type CascaderValue = RawValue | ValueCell[];
export type CascaderOutputValue = ValueCell | ValueCell[];
export type CascaderSelectedOptions = (BaseOptionType | null)[] | (BaseOptionType | null)[][];
export type CascaderSearchConfig = Omit<SearchConfig, 'render' | 'searchValue' | 'onSearch'>;
export interface CascaderSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: { root?: string; list?: string; listItem?: string };
}
export interface CascaderSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: { root?: CSSProperties; list?: CSSProperties; listItem?: CSSProperties };
}
export interface CascaderPanelProps {
  prefixCls?: string;
  options?: BaseOptionType[];
  value?: CascaderValue;
  defaultValue?: CascaderValue;
  multiple?: boolean;
  fieldNames?: FieldNames;
  changeOnSelect?: boolean;
  showCheckedStrategy?: ShowCheckedStrategy;
  loadData?: (selectedOptions: BaseOptionType[]) => void | Promise<void>;
  expandTrigger?: 'click' | 'hover';
  expandIcon?: VNodeChild;
  loadingIcon?: VNodeChild;
  direction?: 'ltr' | 'rtl';
  notFoundContent?: VNodeChild;
  disabled?: boolean;
  popupMenuColumnStyle?: CSSProperties;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderPanelProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderPanelProps>;
  'onUpdate:value'?: (value: CascaderOutputValue) => void;
  onChange?: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
}
export interface CascaderProps extends Omit<CascaderPanelProps, 'classNames' | 'styles'> {
  id?: string;
  checkable?: boolean;
  size?: SizeType;
  loading?: boolean;
  variant?: SelectVariant;
  bordered?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild };
  clearIcon?: VNodeChild;
  removeIcon?: VNodeChild;
  suffixIcon?: VNodeChild;
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  showSearch?: boolean | CascaderSearchConfig;
  searchValue?: string;
  autoClearSearchValue?: boolean;
  placeholder?: VNodeChild;
  popupClassName?: string;
  dropdownClassName?: string;
  popupStyle?: CSSProperties;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement;
  status?: 'error' | 'warning';
  maxTagCount?: number;
  maxTagTextLength?: number;
  maxTagPlaceholder?: VNodeChild;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderProps>;
  'onUpdate:open'?: (open: boolean) => void;
  'onUpdate:searchValue'?: (value: string) => void;
  onOpenChange?: (open: boolean) => void;
  onSearch?: (value: string) => void;
  onFocus?: (event: FocusEvent) => void;
  onBlur?: (event: FocusEvent) => void;
  onClear?: () => void;
  onPopupScroll?: (event: Event) => void;
  onKeydown?: (event: KeyboardEvent) => void;
  onKeyup?: (event: KeyboardEvent) => void;
  onMousedown?: (event: MouseEvent) => void;
}
export interface CascaderEmits {
  'update:value': (value: CascaderOutputValue) => void;
  change: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
  'update:open': (open: boolean) => void;
  openChange: (open: boolean) => void;
  'update:searchValue': (value: string) => void;
  search: (value: string) => void;
  focus: (event: FocusEvent) => void;
  blur: (event: FocusEvent) => void;
  clear: () => void;
  popupScroll: (event: Event) => void;
  keydown: (event: KeyboardEvent) => void;
  keyup: (event: KeyboardEvent) => void;
  mousedown: (event: MouseEvent) => void;
}
export interface CascaderOptionSlots {
  optionRender?: (scope: { option: BaseOptionType; pathOptions: BaseOptionType[] }) => VNodeChild;
  searchRender?: (scope: {
    inputValue: string;
    pathOptions: BaseOptionType[];
    fieldNames: FieldNames;
  }) => VNodeChild;
  expandIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
  loadingIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
}
export interface CascaderPanelSlots extends CascaderOptionSlots {
  notFoundContent?: () => VNodeChild;
}
export interface CascaderSlots extends CascaderPanelSlots {
  default?: () => VNodeChild;
  placeholder?: () => VNodeChild;
  displayRender?: (scope: {
    labels: VNodeChild[];
    selectedOptions: (BaseOptionType | null)[];
  }) => VNodeChild;
  suffixIcon?: SelectSlots['suffixIcon'];
  searchIcon?: SelectSlots['suffixIcon'];
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  maxTagPlaceholder?: (scope: {
    omittedValues: { value: ValueCell; label: VNodeChild; disabled?: boolean }[];
  }) => VNodeChild;
  popupRender?: (scope: { menu: VNode }) => VNodeChild;
}
export interface CascaderRef {
  readonly nativeElement: HTMLElement | null;
  focus: (options?: FocusOptions) => void;
  blur: () => void;
}
```

### ../../_internal/use-merge-semantic.ts

````ts
/**
 * 语义化 `classNames` / `styles` 的合并。
 *
 * 契约来源：antd 6.6.4 的 `es/_util/hooks/useMergeSemantic/index.js`（**逐条对齐**）。
 *
 * 为什么单独抽出来：72 个组件里有 60 多个都有 `classNames` / `styles`，合并语义
 * 一旦不一致，就会出现「Button 的覆盖优先级和 Empty 不一样」这类只有用户才会发现的问题。
 * 所以合并规则集中在这里，组件只声明「合并哪些来源、按什么顺序」。
 *
 * ── 与 antd 的对应关系（合并顺序是契约，不能改）────────────────────────────────
 *
 * ```
 * // antd（Empty）
 * const [mergedClassNames, mergedStyles] = useMergeSemantic(
 *   [contextClassNames, classNames],                          // classNamesList
 *   [contextStyles, contextStyleRoot, styles, styleRoot],     // stylesList
 *   { props },
 * );
 * ```
 *
 * 其中 `contextStyleRoot = useSemanticRootStyle(contextStyle)`、`styleRoot = useSemanticRootStyle(style)`，
 * 即把 `style` 这个平铺的 prop 包成 `{ root: style }` 再进合并。
 *
 * 三条必须逐字保留的判据：
 *   1. **classNames 是「拼接」不是「覆盖」** —— `clsx(acc[key], curVal)`，同名键会连起来。
 *   2. **styles 是「逐键浅合并、后者胜」** —— 与 classNames 不同，这里不是拼接。
 *   3. **`style` prop 排在 `styles.root` 之后** —— 所以 `style` 会**覆盖** `styles.root`。
 *      这条最反直觉，也最容易被「顺手改成更合理的顺序」。
 *
 * ── 函数式变体（裁决 `empty-semantic-fn` = B：支持）───────────────────────────
 *
 * antd 允许传 `(info: { props }) => 对象`。我们在 `resolveSemantic` 里逐字对应：
 * 判据是 `isFunction(value) ? value(info) : value`，**没有**额外的「只在需要时求值」优化
 * —— 那种优化会让函数式与对象式的行为出现差异。
 *
 * ── `schema`（嵌套语义槽）—— **2026-10-03 补齐** ──────────────────────────────
 *
 * antd 的第四参 `schema` 用 `_default` 把「字符串形态的嵌套键」落到指定子槽
 * （`classNames.popup = 'x'` ≡ `classNames.popup = { root: 'x' }`），并在最后用
 * `fillObjectBySchema` 保证嵌套键**恒为对象**。
 *
 * 本仓此前没有它，用「只要有一侧是对象就递归」绕过 —— 那在**字符串与对象混用**时
 * 会产垃圾键（`Object.keys('x')`）。antd 6.6.4 里 **9 个组件**传了 schema
 * （`select` / `cascader` / `color-picker` / `menu` / `tabs` / `image` / `splitter` /
 * `input.Search` / `table`），Table 是第一个**真的需要**它的（`body.cell` / `header.cell`）。
 *
 * ⚠️ **两条语义并存、不能合并**：不给 schema 时保持本仓既有行为（7 个消费者钉住它），
 *    给了 schema 才走 antd 的 `mergeClassNamesBySchema`。
 *    判据见 `__tests__/use-merge-semantic.test.ts` 的「反向哨兵」那一条。
 *
 * ── 这个模块没有证明什么 ──────────────────────────────────────────────────────
 *   - 没证明各组件的**合并顺序声明**是对的。本模块只保证「给定顺序，合并结果正确」；
 *     顺序本身由各组件的 compat 用例与 antd 对照（Empty 见 `__tests__/semantic.test.ts`）。
 *   - 没证明**所有该传 schema 的组件都传了**。schema 档 2026-10-03 实现，
 *     select / cascader / color-picker / tabs / image（×2）/ splitter 已补第四参；
 *     menu 无语义通道、`input.Search` 未实现（见 `docs/KNOWN-ISSUES.md` §2 留痕）。
 *
 *   ⚠️ 无 schema 的宽松路径（`mergeClassNames`）**仍在服务既有消费者**：它在
 *     「字符串 + 对象混用」时会产垃圾键（`Object.keys('x')`）。这条**曾**登记在
 *     `docs/KNOWN-ISSUES.md`，该文件的 §1 已于 2026-10-07 清零、登记项转入 §2 的
 *     「已修 / 已裁决」；但宽松路径本身**未改**（7 个既有消费者的用例钉住它）。
 *     若将来统一到 schema 档，需同步改这 7 处并重跑它们的 L4/L6。
 */

import { isFunction } from '@apollo-design/utils';
import {
  type ComputedRef,
  type CSSProperties,
  computed,
  type MaybeRefOrGetter,
  toValue,
} from 'vue';

/** 函数式语义化拿到的上下文。与 antd 的 `{ props }` 同构。 */
export interface SemanticInfo<P> {
  props: P;
}

/** 对象式或函数式的语义化输入。 */
export type SemanticInput<T, P> = T | ((info: SemanticInfo<P>) => T | undefined);

/** 任意可响应化的输入。普通值、ref、getter 都接受（与 `toValue` 同构）。 */
export type MaybeSource<T> = MaybeRefOrGetter<T>;

/**
 * ⚠️ **刻意不用** `_internal/clsx.ts` 那一份（2026-10-07 核对过）。
 *
 * 这里是**更窄**的语义：只保留字符串，数字 / 数组 / 对象一律丢弃。
 * 而共享层那份会展开数组与对象（`{a:true}` → `'a'`）。语义化 `classNames` 的槽位值
 * 本来就是字符串，宽版本在这里只会把「传错了形态」静默变成一个类名。
 * ⇒ 别为了「消重」把它换成共享版 —— 那份窄语义是有意的。
 */
function clsx(...values: unknown[]): string {
  return values.filter((v) => typeof v === 'string' && v !== '').join(' ');
}

/**
 * 求值一个语义化输入。
 *
 * 与 antd 的 `resolveStyleOrClass(value, info)` 逐字对应 —— 包括
 * **只在 `isFunction` 时求值**这一点：传 `null` / `undefined` 会原样返回，
 * 由下游的 `filter(Boolean)` 丢掉。
 */
export function resolveSemantic<T, P>(
  value: SemanticInput<T, P> | undefined | null,
  info: SemanticInfo<P>,
): T | undefined {
  if (value === undefined || value === null) return undefined;
  return isFunction(value) ? (value as (i: SemanticInfo<P>) => T | undefined)(info) : value;
}

/**
 * 合并 classNames。**拼接**语义：同名键连起来，不覆盖。
 *
 * 与 antd 的 `mergeClassNames(schema, ...classNames)` 在 `schema === undefined` 时等价。
 *
 * ⚠️ 实现里有一次类型断言（`as Record<string, string | undefined>`）。
 *    它**不是**类型漏洞，而是「语义键集合由调用方的泛型决定」这一事实的必然结果：
 *    函数体只做键的遍历与字符串拼接，不认识任何具体键。用 `as any` 才是漏洞，
 *    这里断言到的是精确的中间形态。
 */
export function mergeClassNames<CN extends object>(
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const cur = record[key];
      const prev = acc[key];
      // 嵌套语义对象（如 Select 的 classNames.popup.{root,list,listItem}）递归合并；
      // 叶子值按 clsx 拼接（select 期 AutoComplete 抓出：浅合并在 popup 上丢数据）
      if (isPlainRecord(cur) || isPlainRecord(prev)) {
        acc[key] = mergeClassNames((prev ?? {}) as never, (cur ?? {}) as never);
      } else {
        acc[key] = clsx(prev as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

function isPlainRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// ---------------------------------------------------------------------------
// schema（嵌套语义槽）—— antd `useMergeSemantic` 的第四参
// ---------------------------------------------------------------------------

/**
 * schema 的**键名首字符**集合。
 *
 * 与 antd 的 `ValidChar`（`_util/type.ts:91`）**逐字相同**：**只有小写 a–z**。
 * 这不是「随便写的」—— 它正是让 `_default`（下划线开头）**不落进**索引签名、
 * 从而不与 `{ _default?: string }` 冲突的机制。
 * ⇒ 别「顺手」把大写或下划线加进来（会让 `SemanticSchema` 立刻变成 `never` 交叉）。
 */
type LowerChar =
  | 'a'
  | 'b'
  | 'c'
  | 'd'
  | 'e'
  | 'f'
  | 'g'
  | 'h'
  | 'i'
  | 'j'
  | 'k'
  | 'l'
  | 'm'
  | 'n'
  | 'o'
  | 'p'
  | 'q'
  | 'r'
  | 's'
  | 't'
  | 'u'
  | 'v'
  | 'w'
  | 'x'
  | 'y'
  | 'z';

/**
 * 嵌套语义槽的映射表。与 antd 的 `SemanticSchema` 同构。
 *
 * `_default: 'root'` 的语义（**逐条来自 antd 的 `mergeClassNames`**）：
 *   - 该键收到**普通对象** ⇒ 递归按子 schema 合并；
 *   - 该键收到**非对象**（字符串）⇒ 落到 `acc[key][_default]`（即 `classNames.popup = 'x'`
 *     ≡ `classNames.popup = { root: 'x' }`）；
 *   - **没有** `_default` 的子 schema（如 `image` 的 `placeholder: {}`）⇒ 只保证该键
 *     恒为对象（`fillObjectBySchema` 的 `||= {}`），不做字符串转换。
 */
export type SemanticSchema = { _default?: string } & {
  [key: `${LowerChar}${string}`]: SemanticSchema;
};

/**
 * 按**任意字符串键**读子 schema。
 *
 * ⚠️ 必须走这层 cast：`SemanticSchema` 的索引签名是 `` `${LowerChar}${string}` ``
 *    （antd 的 `ValidChar` 口径，见上面的注释），而 `Object.keys()` 给的是 `string`
 *    ⇒ 直接写 `schema[key]` 会 **TS7053**。这里的 cast 是**诚实的**：运行时 schema 的键
 *    本来就来自调用方写的对象字面量，`Object.keys` 拿到的正是那些键。
 */
function subSchema(schema: SemanticSchema, key: string): SemanticSchema | undefined {
  return (schema as Record<string, SemanticSchema | undefined>)[key];
}

/**
 * 按 schema 补齐对象结构（antd `fillObjectBySchema` 逐字）。
 *
 * 两条判据：
 *   ① `_default` 键 ⇒ `newObj[key] ||= {}`（保证**至少是空对象**，不会残留 `undefined`）；
 *   ② 其余子 schema ⇒ 递归（空 schema `{}` 会让该键变成 `{}`）。
 */
export function fillObjectBySchema(
  obj: Record<string, unknown> | undefined,
  schema: SemanticSchema,
): Record<string, unknown> {
  const newObj: Record<string, unknown> = { ...(obj ?? {}) };
  for (const key of Object.keys(schema)) {
    if (subSchema(schema, key)?._default) {
      newObj[key] ||= {};
    } else {
      newObj[key] = fillObjectBySchema(
        newObj[key] as Record<string, unknown> | undefined,
        subSchema(schema, key) as SemanticSchema,
      );
    }
  }
  return newObj;
}

/**
 * **带 schema** 的 classNames 合并（antd `mergeClassNames(schema, ...classNames)` 逐字）。
 *
 * ⚠️ 与下面**无 schema** 的 `mergeClassNames` 是**两条不同的语义**，不要合并：
 *    - 无 schema：只要有一侧是对象就**递归**（本仓在 select/auto-complete 期加的行为，
 *      比 antd 更宽松，且已被 7 个组件的既有用例钉住）；
 *    - 有 schema：**只有 schema 声明过的键**才特殊处理，其余键一律 `clsx` 平铺（antd 语义）。
 *
 *    两者的差别在「字符串 vs 对象混用」时可见：
 *      `classNames: { popup: 'x' }` 与 `{ popup: { root: 'y' } }` 两个来源
 *      —— schema 版给 `popup.root = 'x y'`（正确）；无 schema 版会把 `'x'` 当对象递归
 *      （`Object.keys('x')` ⇒ 垃圾键）。这正是 antd 需要 `_default` 的原因。
 */
export function mergeClassNamesBySchema<CN extends object>(
  schema: SemanticSchema,
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const keySchema = subSchema(schema, key);
      const cur = record[key];
      if (keySchema) {
        if (isPlainRecord(cur)) {
          acc[key] = mergeClassNamesBySchema(keySchema, (acc[key] ?? {}) as never, cur as never);
        } else {
          const defaultField = keySchema._default;
          if (defaultField) {
            const target = (acc[key] ?? {}) as Record<string, unknown>;
            target[defaultField] = clsx(
              target[defaultField] as string | undefined,
              cur as string | undefined,
            );
            acc[key] = target;
          }
        }
      } else {
        acc[key] = clsx(acc[key] as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

/**
 * 合并 styles。**逐键浅合并、后者胜** —— 注意与 classNames 的语义不同。
 *
 * 与 antd 的 `mergeStyles(...styles)` 等价。断言理由同 `mergeClassNames`。
 */
export function mergeStyles<ST extends object>(
  ...sources: readonly (Partial<ST> | undefined)[]
): Partial<ST> {
  const acc: Record<string, CSSProperties | undefined> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, CSSProperties | string | undefined>;
    for (const key of Object.keys(record)) {
      // 🚨 **叶子可能是 CSS 字符串**（Vue 的 `style` attr 允许字符串，而 `attrs.style`
      //    会经 `semanticRootStyle` 进到这里）。直接展开字符串会得到
      //    `{ 0: 'w', 1: 'i', … }` ⇒ Vue 的 `setStyle` 抛
      //    `'set' on proxy: trap returned falsish for property '0'`。
      acc[key] = { ...acc[key], ...normalizeStyleValue(record[key]) };
    }
  }
  return acc as Partial<ST>;
}

/**
 * `'width: 240px; color: red'` → `{ width: '240px', color: 'red' }`。
 *
 * ⚠️ 不引入 `@vue/shared` 的 `parseStringStyle`：它是 `vue` 的**传递依赖**，
 *    直接 import 属于幻影依赖（R7 的精神）。这里只需要支持 `;` 分隔的声明段，
 *    与 Vue 自己的实现判据一致（空段 / 无冒号的段跳过）。
 */
function parseStyleString(text: string): CSSProperties {
  const out: Record<string, string> = {};
  for (const part of text.split(';')) {
    const index = part.indexOf(':');
    if (index < 0) continue;
    const name = part.slice(0, index).trim();
    if (!name) continue;
    out[name] = part.slice(index + 1).trim();
  }
  return out as CSSProperties;
}

/** 样式叶子归一：字符串解析成对象，其余原样。 */
function normalizeStyleValue(value: CSSProperties | string | undefined): CSSProperties | undefined {
  if (typeof value === 'string') {
    return parseStyleString(value);
  }
  return value;
}

/**
 * 把平铺的 `style` 包成 `{ root: style }`。
 *
 * 与 antd 的 `useSemanticRootStyle(style, key = 'root')` 等价 —— 包括
 * 「`style` 为空时返回 `undefined` 而不是 `{ root: undefined }`」这一点：
 * 后者会让 `mergeStyles` 多产出一个 `root` 键，进而在 DOM 上多出一个空的 `style=""`。
 */
export function semanticRootStyle(
  style: CSSProperties | string | undefined,
  key = 'root',
): Record<string, CSSProperties> | undefined {
  if (!style) {
    return undefined;
  }
  // 🚨 `style` 可能是 **CSS 字符串**（`<Input style="width: 240px" />` —— Vue 的 `style`
  //    attr 两种形态都合法）。必须在这里解析成对象，否则下游 `mergeStyles` 的
  //    对象展开会把它拆成 `{ 0: 'w', … }`（Issue #7.1 实测）。
  return { [key]: typeof style === 'string' ? parseStyleString(style) : style };
}

/**
 * 把「可能为空的样式」转成可以直接 `v-bind` 的属性对象。
 *
 * 空样式返回 `{}`（**连 `style` 这个键都没有**），非空返回 `{ style }`。
 *
 * ── 为什么必须做这一步（2026-09-18，empty 实测）──────────────────────────────
 *
 * `mergeStyles()` 的返回值**恒**是对象（可能是 `{}`）。直接绑 `:style` 时：
 *
 * | 渲染路径 | 结果 |
 * |---|---|
 * | 客户端 | `patchStyle` 会把空样式移除 —— 没有 `style` 属性 ✓ |
 * | **SSR** | `ssrRenderAttrs` 对 `style` 键是**无条件**输出的 ⇒ 渲染出 `style=""` ✗ |
 *
 * React（antd）在样式为空时**不输出该属性**。所以 SSR 产物会与上游有差异，
 * 而且每个元素多 9 字节 —— 72 个组件 × 多层结构累积起来是可观的体积。
 *
 * 实测：Empty 一层就有 3 个元素带 `style=""`；改成 `v-bind="styleAttrs(x)"` 后归零。
 *
 * ⚠️ 这个差异 L4 **测不出来** —— 投影会把「没有 style 属性」与 `style=""`
 *    都归一化成空串（`(node.style ?? []).join(';')` 两边都是 `''`）。
 *    它是被渲染 SSR 预览页时肉眼发现的，所以既有 L1 断言也有这里。
 *
 * ⚠️ 所有用 `useMergeSemantic` 的组件都应该这样绑样式，而不是 `:style="mergedStyles.x"`。
 */
export function styleAttrs(style: CSSProperties | undefined): { style?: CSSProperties } {
  if (!style) return {};
  const record = style as Record<string, unknown>;
  for (const key of Object.keys(record)) {
    if (record[key] !== undefined) return { style };
  }
  return {};
}

export interface UseMergeSemanticResult<CN extends object, ST extends object> {
  classNames: ComputedRef<Partial<CN>>;
  styles: ComputedRef<Partial<ST>>;
}

/**
 * 响应式版本的 `useMergeSemantic`。
 *
 * 与 antd 的差别只有一处、且是平台差异（PLATFORM）：antd 每次渲染都重跑一遍合并，
 * 我们用 `computed` 缓存 —— 语义相同，但**依赖必须可追踪**，所以来源要用
 * `() => value` 的形式传，而不是先取值再传。
 *
 * @param classNamesSources 按优先级从低到高排列（后者拼接在前者之后）
 * @param stylesSources 按优先级从低到高排列（后者覆盖前者）
 * @param props 传给函数式变体的 `info.props`。**可以是 getter / ref** ——
 *   函数式变体每次重算都要看到**当前** props。传 `mergedProps.value` 那种
 *   setup 期快照会让 `disabled` / `size` / `variant` 变化后函数式仍按旧值计算
 *   （Issue #3.2）。裸对象仍然可用（`toValue` 原样返回）。
 * @param schema **嵌套语义槽**的映射表（antd 第四参）。给了它就会：
 *   ① classNames 走 `mergeClassNamesBySchema`（`_default` 的字符串→对象转换）；
 *   ② 两个结果都过一遍 `fillObjectBySchema`（保证嵌套键恒为对象）。
 *   ⚠️ 不给时**保持本仓既有行为**（无 schema 的递归合并）—— 7 个既有消费者不受影响。
 */
export function useMergeSemantic<P extends object, CN extends object, ST extends object>(
  classNamesSources: readonly MaybeSource<SemanticInput<Partial<CN>, P> | undefined>[],
  stylesSources: readonly MaybeSource<SemanticInput<Partial<ST>, P> | undefined>[],
  props: MaybeRefOrGetter<P>,
  schema?: SemanticSchema,
): UseMergeSemanticResult<CN, ST> {
  // ⚠️ `info` 必须在**每次重算时**新建，且 `props` 要在 computed 内 `toValue` ——
  //    在 setup 期建一次会把首帧的 props 快照焊死（Issue #3.2）。
  const classNames = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = classNamesSources.map((source) =>
      resolveSemantic<Partial<CN>, P>(toValue(source), info),
    );
    const merged = schema
      ? mergeClassNamesBySchema<CN>(schema, ...resolved)
      : mergeClassNames<CN>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<CN>;
  });

  const styles = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = stylesSources.map((source) =>
      resolveSemantic<Partial<ST>, P>(toValue(source), info),
    );
    const merged = mergeStyles<ST>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<ST>;
  });

  return { classNames, styles };
}
````

### ../../config-provider/size-context.ts

````ts
/**
 * `SizeContext` —— 组件尺寸。
 *
 * 契约来源：antd 6.6.4 的 `es/config-provider/SizeContext.tsx` + `hooks/useSize.ts`。
 *
 * ── 为什么它是**独立 context** 而不是 ConfigContext 的一个字段 ──────────────────
 *
 * antd 把它拆出去是为了「`componentSize` 变化时只重渲染读尺寸的组件」。
 * 本项目的理由更硬：`ConfigContextValue` 是**一个**响应式对象，任何字段变化都会
 * 触发所有读它的 `computed` 重算；而尺寸是被最多组件读的字段之一，独立出来能明显
 * 收窄依赖面。形态上也与 antd 对齐（便于迁移）。
 */

import { type ComputedRef, computed, type InjectionKey, inject } from 'vue';

/**
 * 尺寸。
 *
 * ⚠️ `'medium'` 与 `'middle'` **两个都要**：antd 6 起 `'medium'` 是推荐写法，
 * `'middle'` 仍是默认值且未移除（上游注释：`middle is deprecated and will be removed
 * in v7`）。`COMPONENT-RULES.md` §4 要求枚举值与 antd 一致 ⇒ 不裁剪成 `'medium'`。
 */
export type SizeType = 'small' | 'medium' | 'middle' | 'large';

/**
 * 注入键。
 *
 * 值是 `ComputedRef` 而不是裸值 —— 这样 `useSize` 在 `computed` 里读 `.value`
 * 会被追踪，`componentSize` 变化能传导到下游（对齐 antd 的 context 更新）。
 */
export const sizeContextKey: InjectionKey<ComputedRef<SizeType | undefined>> =
  Symbol('apolloSizeContext');

/**
 * 读取组件尺寸，与自己的 prop 合并。与 antd 的 `useSize` 逐字对应。
 *
 * 四条判据（逐条来自 `hooks/useSize.ts`）：
 *   1. `!customSize` ⇒ 用 context（⚠️ 真值判据：`0` / `''` 也走这一支）。
 *   2. `customSize` 是字符串 ⇒ `customSize ?? size`（字符串恒真，等价于直接返回）。
 *   3. `customSize` 是函数 ⇒ `customSize(size)`。
 *   4. 其余（数字 / 对象）⇒ 用 context。
 *
 * @example
 * ```ts
 * const mergedSize = useSize(props.size);   // ComputedRef<SizeType | undefined>
 * ```
 */
export function useSize<T extends string | number | undefined | object>(
  customSize?: T | ((ctxSize: SizeType | undefined) => T),
): ComputedRef<T | SizeType | undefined> {
  const injected = inject(sizeContextKey, undefined);

  return computed(() => {
    const ctxSize = injected?.value;

    if (!customSize) return ctxSize;

    if (typeof customSize === 'string') return customSize ?? ctxSize;

    if (typeof customSize === 'function') {
      return (customSize as (ctxSize: SizeType | undefined) => T)(ctxSize);
    }

    return ctxSize;
  });
}
````

### ../../select/interface.ts

```ts
/** Public Vue contracts for Select and its option data. */

import type { CSSProperties, VNodeChild } from 'vue';
import type { SizeType } from '../config-provider/size-context';

// ---------------------------------------------------------------------------
// 基础值类型
// ---------------------------------------------------------------------------

export type RawValueType = string | number;

/** antd 的 `SelectValue`。 */
export type SelectValue =
  | RawValueType
  | RawValueType[]
  | LabeledValue
  | LabeledValue[]
  | null
  | undefined;

/** antd 的 `LabeledValue`（labelInValue 的输出形态）。 */
export interface LabeledValue {
  key?: RawValueType;
  value: RawValueType;
  label?: unknown;
}

/** rc 的内部形态（`labelInValue` 的中间表示）。 */
export interface LabelInValueType {
  label?: unknown;
  value: RawValueType;
  key?: RawValueType;
  disabled?: boolean;
  title?: string;
}

export interface BaseOptionType {
  disabled?: boolean;
  className?: string;
  style?: CSSProperties;
  title?: string;
  [name: string]: unknown;
}

export interface DefaultOptionType extends BaseOptionType {
  label?: unknown;
  value?: RawValueType | null;
  children?: Omit<DefaultOptionType, 'children'>[];
  options?: DefaultOptionType[];
}

export type SelectOptionType = BaseOptionType | DefaultOptionType;

/** antd `OptionProps`（`Select.Option` / `Select.OptGroup`，deprecated 但保留）。 */
export interface OptionProps extends BaseOptionType {
  value?: RawValueType | null;
  children?: unknown;
}

export interface OptGroupProps extends BaseOptionType {
  label?: unknown;
  children?: unknown;
}

// ---------------------------------------------------------------------------
// 模式 / 尺寸 / 状态
// ---------------------------------------------------------------------------

/**
 * 公开模式只有 `multiple` / `tags` —— antd 把 `mode="combobox"` 吞成单选
 * （`index.tsx` 的 `mode` memo），只有 `SECRET_COMBOBOX_MODE_DO_NOT_USE` 才真走
 * combobox（AutoComplete 用）。内核实现 combobox 分支，公开类型不声明。
 */
export type SelectMode = 'multiple' | 'tags';

/** 内核模式（engine 内部用）。 */
export type InternalSelectMode = SelectMode | 'combobox';

/**
 * 尺寸。**直接别名到 `config-provider` 的 `SizeType`**（`'small' | 'medium' | 'middle' | 'large'`）。
 *
 * 上游 `SelectProps.size` 就是 `SizeType`；此前手抄成 `'small' | 'middle' | 'large'`
 * 漏了 `medium`（运行时 `useSize` 是吃 `SizeType` 的 ⇒ 类型比运行时窄，Issue #4.3）。
 */
export type SelectSize = SizeType;

export type SelectVariant = 'outlined' | 'borderless' | 'filled' | 'underlined';

export type SelectStatus = 'error' | 'warning' | 'success' | 'validating';

/** antd `SelectCommonPlacement`（`_util/motion.ts` 的 4 值）。 */
export type SelectCommonPlacement = 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight';

export type SelectDirection = 'ltr' | 'rtl';

// ---------------------------------------------------------------------------
// 搜索配置
// ---------------------------------------------------------------------------

export type FilterFunc<OptionType> = (inputValue: string, option: OptionType) => boolean;

export interface SearchConfig<OptionType = DefaultOptionType> {
  autoClearSearchValue?: boolean;
  filterOption?: boolean | FilterFunc<OptionType>;
  filterSort?: (optionA: OptionType, optionB: OptionType, info: { searchValue: string }) => number;
  optionFilterProp?: string | string[];
}

export type SelectSearchConfig = SearchConfig<DefaultOptionType>;

// ---------------------------------------------------------------------------
// 语义槽（classNames / styles）
// ---------------------------------------------------------------------------

export interface SelectSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: {
    root?: string;
    listItem?: string;
    list?: string;
  };
}

export interface SelectSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: {
    root?: CSSProperties;
    listItem?: CSSProperties;
    list?: CSSProperties;
  };
}

export interface FieldNames {
  value?: string;
  label?: string;
  groupLabel?: string;
  options?: string;
}

// ---------------------------------------------------------------------------
// Engine content function types; public component content uses slots.
// ---------------------------------------------------------------------------

/** `FlattenOptionData`（rc `interface.d.ts`）。 */
export interface FlattenOptionData<OptionType = DefaultOptionType> {
  label?: unknown;
  data: OptionType;
  key: string | number;
  value?: RawValueType;
  groupOption?: boolean;
  group?: boolean;
}

/** 选择器里一个已选值的展示形态（rc `DisplayValueType`）。 */
export interface DisplayValueType {
  key?: string | number;
  value?: RawValueType;
  label?: unknown;
  title?: unknown;
  disabled?: boolean;
  index?: number;
}

/** `tagRender` 的入参（rc `CustomTagProps`）。 */
export interface CustomTagProps {
  label?: unknown;
  value?: RawValueType;
  disabled: boolean;
  onClose: (event?: MouseEvent) => void;
  closable: boolean;
  isMaxTag: boolean;
  index?: number;
}

export type OptionRenderFn = (
  option: FlattenOptionData<DefaultOptionType>,
  info: { index: number },
) => VNodeChild;

export type LabelRenderFn = (props: LabelInValueType) => VNodeChild;

export type TagRenderFn = (props: CustomTagProps) => VNodeChild;

export type PopupRenderFn = (menu: unknown) => VNodeChild;

export type ScrollToArg =
  | number
  | {
      index?: number;
      align?: 'top' | 'bottom' | 'auto';
      key?: string | number;
    };

// ---------------------------------------------------------------------------
// 实例句柄（antd `RefSelectProps` = rc `BaseSelectRef`）
// ---------------------------------------------------------------------------

export interface SelectRef {
  focus: (options?: FocusOptions) => void;
  blur: () => void;
  scrollTo: (arg?: ScrollToArg) => void;
  nativeElement: HTMLElement | null;
}

// ---------------------------------------------------------------------------
// Props
// ---------------------------------------------------------------------------

export interface SelectProps<ValueType = SelectValue> {
  // ---- 身份 ----
  id?: string;
  prefixCls?: string;
  /** ⚠️ Vue 原生 `class` / `style` 走 attrs（不是 prop）；这里只为类型面留位。 */
  class?: unknown;

  // ---- 值 ----
  value?: ValueType;
  defaultValue?: ValueType;
  /** 输出 `{ label, value }` 而非裸值。 */
  labelInValue?: boolean;
  /** 回填值取 option 的哪个字段（默认 `label`）。 */
  optionLabelProp?: string;
  fieldNames?: FieldNames;

  // ---- 模式 ----
  mode?: SelectMode;

  // ---- 选项 ----
  options?: DefaultOptionType[];
  /** 搜索时列表的最大高度（默认 256）。 */
  listHeight?: number;
  /** 虚拟滚动的估算行高（默认 controlHeight = 32）。 */
  listItemHeight?: number;
  virtual?: boolean;
  /** 键盘上下键是否自动激活第一项（默认 true，combobox 为 false）。 */
  defaultActiveFirstOption?: boolean;
  // ---- 搜索 ----
  showSearch?: boolean | SelectSearchConfig;
  /** Search text; supports v-model:searchValue. */
  searchValue?: string;
  /** @deprecated 用 `showSearch.autoClearSearchValue` */
  autoClearSearchValue?: boolean;
  /** @deprecated 用 `showSearch.filterOption` */
  filterOption?: boolean | FilterFunc<DefaultOptionType>;
  /** @deprecated 用 `showSearch.filterSort` */
  filterSort?: SearchConfig<DefaultOptionType>['filterSort'];
  /** @deprecated 用 `showSearch.optionFilterProp` */
  optionFilterProp?: string | string[];

  // ---- 外观 ----
  size?: SelectSize;
  variant?: SelectVariant;
  /** @deprecated 用 `variant` */
  bordered?: boolean;
  status?: SelectStatus;
  disabled?: boolean;
  loading?: boolean;
  placeholder?: string;
  /** @deprecated 默认显示箭头，隐藏请用空的 `#suffixIcon` 插槽或 `showArrow: false` */
  showArrow?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild; label?: string };
  maxLength?: number;

  // ---- 多选 ----
  maxCount?: number;
  maxTagCount?: number;
  maxTagTextLength?: number;
  tokenSeparators?: string[] | ((input: string) => string[]);

  // ---- 浮层 ----
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  direction?: SelectDirection;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement | ShadowRoot;
  transitionName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  popupClassName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  dropdownClassName?: string;
  /** @deprecated 用 `styles.popup.root` */
  dropdownStyle?: CSSProperties;
  popupStyle?: CSSProperties;

  // ---- 语义槽 ----
  classNames?: SelectSemanticClassNames;
  styles?: SelectSemanticStyles;

  // ---- 无障碍 ----
  tabIndex?: number;
  autoFocus?: boolean;
  title?: string;
  role?: string;
}

// ---------------------------------------------------------------------------
// 事件（Vue 侧：语义事件 + v-model 同发，见 PITFALLS 162）
// ---------------------------------------------------------------------------

export interface SelectEmits<ValueType = SelectValue> {
  change: [value: ValueType, option: DefaultOptionType | DefaultOptionType[] | undefined];
  'update:value': [value: ValueType];
  select: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  deselect: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  search: [value: string];
  'update:searchValue': [value: string];
  openChange: [open: boolean];
  'update:open': [open: boolean];
  focus: [event: FocusEvent];
  blur: [event: FocusEvent];
  clear: [];
  popupScroll: [event: Event];
  inputKeyDown: [event: KeyboardEvent];
}

// ---------------------------------------------------------------------------
// Slots（规则 C8-R2：ReactNode / render prop 一律 slot —— **不**保留同名 prop。
// 文本类 prop（placeholder）保留 string 便捷形态，slot 优先。）
// ---------------------------------------------------------------------------

export interface SelectSlots {
  default?: () => VNodeChild;
  prefix?: () => VNodeChild;
  suffixIcon?: (props: {
    searchValue: string;
    open: boolean;
    focused: boolean;
    showSearch: boolean;
    loading?: boolean;
  }) => VNodeChild;
  searchIcon?: () => VNodeChild;
  loadingIcon?: () => VNodeChild;
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  menuItemSelectedIcon?: (props: {
    value?: unknown;
    disabled?: boolean;
    isSelected?: boolean;
  }) => VNodeChild;
  placeholder?: () => VNodeChild;
  notFoundContent?: () => VNodeChild;
  optionRender?: (props: {
    option: FlattenOptionData<DefaultOptionType>;
    index: number;
  }) => VNodeChild;
  tagRender?: (props: CustomTagProps) => VNodeChild;
  labelRender?: (props: LabelInValueType) => VNodeChild;
  popupRender?: (props: { menu: VNodeChild }) => VNodeChild;
  maxTagPlaceholder?: (props: { omittedValues: DisplayValueType[] }) => VNodeChild;
}
```

### ../hooks/search.ts

```ts
/**
 * Cascader 的搜索 hooks —— `useSearchConfig` / `useSearchOptions` 的 Vue 版。
 *
 * 判据（docs/analysis/cascader.md §3.4）：
 * - `showSearch` 为对象时合入默认配置（`matchInputWidth: true` / `limit: 50`）；
 * - `limit <= 0` 视为 false（不限制）；
 * - 过滤只在**叶子**（或 changeOnSelect / 多选的任意层）上做；命中的结果项用
 *   `render` 产出 label（antd 薄壳会注入带高亮的 render），并挂 `SEARCH_MARK`
 *   保存完整路径（展示与回填都需要它）；
 * - `sort` 提供时覆盖默认顺序。
 */

import { type ComputedRef, computed, type Ref } from 'vue';

import {
  type BaseOptionType,
  type FieldNames,
  type FilledFieldNames,
  fillFieldNames,
  getOptionChildren,
  getOptionLabel,
  getOptionValue,
  getSearchPath,
  SEARCH_MARK,
} from '../utils';

export interface SearchConfig {
  filter?: (
    searchValue: string,
    pathOptions: BaseOptionType[],
    fieldNames: { label: string },
  ) => boolean;
  render?: (
    inputValue: string,
    pathOptions: BaseOptionType[],
    prefixCls: string,
    fieldNames: FieldNames,
  ) => unknown;
  sort?: (
    a: BaseOptionType[],
    b: BaseOptionType[],
    searchValue: string,
    fieldNames: FieldNames,
  ) => number;
  matchInputWidth?: boolean;
  limit?: number | false;
  autoClearSearchValue?: boolean;
}

/** `showSearch` → [是否开启, 配置]（上游 useSearchConfig）。 */
export function normalizeSearchConfig(
  showSearch: boolean | Omit<SearchConfig, 'render'> | undefined,
  props: { autoClearSearchValue?: boolean },
): [boolean, SearchConfig] {
  if (!showSearch) return [false, {}];

  let searchConfig: SearchConfig = {
    matchInputWidth: true,
    limit: 50,
    autoClearSearchValue: props.autoClearSearchValue,
  };
  if (showSearch && typeof showSearch === 'object') {
    const {
      filter,
      sort,
      matchInputWidth = true,
      limit = 50,
      autoClearSearchValue = props.autoClearSearchValue,
    } = showSearch;
    searchConfig = { filter, sort, matchInputWidth, limit, autoClearSearchValue };
  }
  if (typeof searchConfig.limit === 'number' && searchConfig.limit <= 0) {
    searchConfig.limit = false;
  }
  return [true, searchConfig];
}

const defaultFilter = (
  search: string,
  options: BaseOptionType[],
  { label = '' }: { label?: string },
): boolean =>
  options.some((opt) =>
    String(opt[label] ?? '')
      .toLowerCase()
      .includes(search.toLowerCase()),
  );

const defaultRender = (
  _inputValue: string,
  path: BaseOptionType[],
  _prefixCls: string,
  fieldNames: FieldNames,
): unknown => {
  const fields = fillFieldNames(fieldNames);
  const labels = path.map((option) =>
    getOptionLabel(option, fields, getOptionValue(option, fields)),
  );
  return labels.every((label) => typeof label === 'string' || typeof label === 'number')
    ? labels.join(' / ')
    : labels.flatMap((label, index) => (index ? [' / ', label] : [label]));
};

/** 搜索态的候选 options（过滤 + render + limit + sort；上游 useSearchOptions）。 */
export function computeSearchOptions(
  search: string,
  options: BaseOptionType[],
  fieldNames: FilledFieldNames,
  prefixCls: string,
  config: SearchConfig,
  enableHalfPath: boolean,
): BaseOptionType[] {
  const { filter = defaultFilter, render = defaultRender, limit = 50, sort } = config;

  const filteredOptions: BaseOptionType[] = [];
  if (!search) return [];

  function dig(
    list: BaseOptionType[],
    pathOptions: BaseOptionType[],
    parentDisabled = false,
  ): void {
    list.forEach((option) => {
      // 无 sort 且有 limit 时攒够即停（上游的 perf saving）
      if (!sort && limit !== false && limit > 0 && filteredOptions.length >= limit) return;

      const connectedPathOptions = [...pathOptions, option];
      const children = getOptionChildren(option, fieldNames);
      const mergedDisabled = parentDisabled || !!option.disabled;

      // 只在叶子（或 changeOnSelect / 多选的任意层）上做过滤
      if (!children || children.length === 0 || enableHalfPath) {
        if (filter(search, connectedPathOptions, { label: fieldNames.label })) {
          filteredOptions.push({
            ...option,
            disabled: mergedDisabled,
            [fieldNames.label]: render(search, connectedPathOptions, prefixCls, {
              label: fieldNames.label,
              value: fieldNames.value,
              children: fieldNames.children,
            }),
            [SEARCH_MARK]: connectedPathOptions,
            [fieldNames.children]: undefined,
          });
        }
      }
      if (children) {
        dig(children, connectedPathOptions, mergedDisabled);
      }
    });
  }
  dig(options, []);

  if (sort) {
    filteredOptions.sort((a, b) =>
      sort(getSearchPath(a) ?? [], getSearchPath(b) ?? [], search, {
        label: fieldNames.label,
        value: fieldNames.value,
        children: fieldNames.children,
      }),
    );
  }
  return limit !== false && limit > 0 ? filteredOptions.slice(0, limit) : filteredOptions;
}

/** 响应式包装（供组件层使用）。 */
export function useSearchOptions(
  search: Ref<string>,
  options: ComputedRef<BaseOptionType[]>,
  fieldNames: Ref<FilledFieldNames>,
  prefixCls: Ref<string>,
  config: Ref<SearchConfig>,
  enableHalfPath: boolean,
): ComputedRef<BaseOptionType[]> {
  return computed(() =>
    computeSearchOptions(
      search.value,
      options.value,
      fieldNames.value,
      prefixCls.value,
      config.value,
      enableHalfPath,
    ),
  );
}
```

### ../utils.ts

```ts
import { isVNode, type VNodeChild } from 'vue';
import { convertDataToEntities, type DataEntity } from './engine/tree';

/** Internal path keys retain both the value type and path boundaries. */
export const SHOW_PARENT = 'SHOW_PARENT';
export const SHOW_CHILD = 'SHOW_CHILD';
export type ShowCheckedStrategy = typeof SHOW_PARENT | typeof SHOW_CHILD;
export interface FieldNames {
  label?: string;
  value?: string;
  children?: string;
}
export interface FilledFieldNames {
  label: string;
  value: string;
  key: string;
  children: string;
}
export type BaseOptionType = Record<string, unknown> & {
  disabled?: boolean;
  isLeaf?: boolean;
  loading?: boolean;
};
export type DefaultOptionType = BaseOptionType & {
  label?: VNodeChild;
  value?: string | number;
  children?: DefaultOptionType[];
};
export type ValueCell = (string | number)[];
export type RawValue = string | number | ValueCell;

export function toPathKey(value: ValueCell): string {
  return JSON.stringify(value);
}
export function toPathKeys(values: ValueCell[]): string[] {
  return values.map(toPathKey);
}
export function toPathValueStr(pathKey: string): string[] {
  const value: unknown = JSON.parse(pathKey);
  if (!Array.isArray(value) || !value.every(isValue))
    throw new TypeError('[Cascader] Invalid path key');
  return value.map(String);
}
export function fillFieldNames(fieldNames?: FieldNames): FilledFieldNames {
  const { label = 'label', value = 'value', children = 'children' } = fieldNames ?? {};
  return { label, value, key: value, children };
}
export function isValue(value: unknown): value is string | number {
  return typeof value === 'string' || typeof value === 'number';
}
export function getOptionValue(option: BaseOptionType, fields: FilledFieldNames): string | number {
  const value = option[fields.value];
  if (!isValue(value))
    throw new TypeError(`[Cascader] Option ${fields.value} must be a string or number`);
  return value;
}
export function isOption(value: unknown): value is BaseOptionType {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}
export function getOptionChildren(
  option: BaseOptionType | undefined,
  fields: FilledFieldNames,
): BaseOptionType[] {
  const children = option?.[fields.children];
  if (children === undefined || children === null) return [];
  if (!Array.isArray(children) || !children.every(isOption))
    throw new TypeError(`[Cascader] Option ${fields.children} must be an array of options`);
  return children;
}
export function getSearchPath(option: BaseOptionType): BaseOptionType[] | undefined {
  const path = option[SEARCH_MARK];
  return Array.isArray(path) && path.every(isOption) ? path : undefined;
}
export function toContent(value: unknown): VNodeChild {
  if (
    value === undefined ||
    value === null ||
    typeof value === 'string' ||
    typeof value === 'number' ||
    typeof value === 'boolean' ||
    isVNode(value)
  )
    return value;
  if (Array.isArray(value)) return value.map(toContent);
  throw new TypeError('[Cascader] Option labels must be Vue renderable content');
}
export function getOptionLabel(
  option: BaseOptionType | null,
  fields: FilledFieldNames,
  fallback: string | number,
): VNodeChild {
  const label = option?.[fields.label];
  return label === undefined ? fallback : toContent(label);
}
export function isLeaf(option: BaseOptionType | undefined, fields: FilledFieldNames): boolean {
  return option?.isLeaf ?? getOptionChildren(option, fields).length === 0;
}
export function scrollIntoParentView(element: HTMLElement): void {
  const parent = element.parentElement;
  if (!parent) return;
  const offset = element.offsetTop - parent.offsetTop;
  if (offset < parent.scrollTop) parent.scrollTo({ top: offset });
  else if (offset + element.clientHeight > parent.scrollTop + parent.clientHeight)
    parent.scrollTo({ top: offset + element.clientHeight - parent.clientHeight });
}
export const SEARCH_MARK = '__rc_cascader_search_mark__';
export function getFullPathKeys(
  options: BaseOptionType[],
  fields: FilledFieldNames,
): (ValueCell | undefined)[] {
  return options.map((option) =>
    getSearchPath(option)?.map((node) => getOptionValue(node, fields)),
  );
}
function isValueCell(value: unknown): value is ValueCell {
  return Array.isArray(value) && value.every(isValue);
}
export function toRawValues(value: RawValue | RawValue[] | undefined): ValueCell[] {
  if (value === undefined) return [];
  if (isValue(value)) return [[value]];
  if (!value.length) return [];
  if (isValueCell(value)) return [value];
  return value.map((path) => {
    if (!isValueCell(path))
      throw new TypeError('[Cascader] Values must be paths of strings or numbers');
    return path;
  });
}
export function formatStrategyValues(
  pathKeys: string[],
  getEntities: () => Record<string, DataEntity>,
  strategy: ShowCheckedStrategy,
): string[] {
  const checked = new Set(pathKeys);
  const entities = getEntities();
  return pathKeys.filter((key) => {
    const entity = Object.hasOwn(entities, key) ? entities[key] : undefined;
    if (entity?.node.disabled) return true;
    return strategy === SHOW_CHILD
      ? !entity?.children?.some((child) => checked.has(child.key))
      : !(entity?.parent && !entity.parent.node.disabled && checked.has(entity.parent.key));
  });
}
export interface PathOption {
  value: string | number;
  index: number;
  option: BaseOptionType | null;
}
export function toPathOptions(
  path: ValueCell,
  options: BaseOptionType[],
  fields: FilledFieldNames,
  stringMode = false,
): PathOption[] {
  let list = options;
  return path.map((value) => {
    const index = list.findIndex((option) =>
      stringMode ? String(option[fields.value]) === String(value) : option[fields.value] === value,
    );
    const option = list[index] ?? null;
    list = getOptionChildren(option ?? undefined, fields);
    return { value: option ? getOptionValue(option, fields) : value, index, option };
  });
}
export { convertDataToEntities };
```

### ../engine/tree.ts

```ts
/**
 * Cascader 依赖的两棵「树算法」—— `@rc-component/tree` 的 Vue 版移植。
 *
 * ── 为什么在这里，而不是独立包 ──────────────────────────────────────────────
 *
 * `foundation.json` 的开放决策 `early-extract-table-core-tree-core` 结论是
 * **A：不提前抽取独立包，等第二个消费者出现**。Cascader（多选的勾选传导）是第一个
 * 消费者，所以算法先落在 `cascader/engine/`；将来 Tree 组件需要时再按
 * `ActionButton` 那套做法提升到 `_internal/`（原位置留垫片）。
 *
 * ── 两个算法 ────────────────────────────────────────────────────────────────
 *
 * 1. `convertDataToEntities(dataNodes, config)` —— 把嵌套 options 摊成扁平实体表，
 *    并补出 `parent` / `children`（实体层面）与 `level` / `pos` / `nodes`（路径）。
 * 2. `conductCheck(keyList, checked, keyEntities)` —— 勾选传导：
 *    - `checked === true`（fill）：父选中 ⇒ 向下补全所有子；子全选 ⇒ 向上补父；
 *      部分选中 ⇒ 父记 halfChecked。
 *    - `checked === { checked: false, halfCheckedKeys }`（clean）：反向清理。
 *
 * 契约来源：`@rc-component/tree@1.x` 的 `es/utils/treeUtil.js`（convertDataToEntities /
 * traverseDataNodes）与 `es/utils/conductUtil.js`（conductCheck / fill+clean）。
 * 行为逐条对齐，**不复制源码**。
 */

/** 树节点实体。 */
export interface DataEntity {
  /** 原始节点。 */
  node: Record<string, unknown>;
  /** 从根到当前节点的原始节点链（Cascader 用它拼 pathKey）。 */
  nodes: Record<string, unknown>[];
  /** 在同级中的下标。 */
  index: number;
  /** 节点 key（`getKey(key, pos)`：key 缺失时回退 pos）。 */
  key: string;
  /** 位置串（形如 `0-1-2`）。 */
  pos: string;
  /** 层级（根为 0）。 */
  level: number;
  /** 父实体（根为 undefined）。 */
  parent?: DataEntity;
  /** 子实体列表（构造期填充）。 */
  children?: DataEntity[];
}

export interface Wrapper {
  posEntities: Record<string, DataEntity>;
  keyEntities: Record<string, DataEntity>;
  [key: string]: unknown;
}

export interface ConvertConfig {
  /** 用自定义字段解析（Cascader 传 `{ key: value字段, children }`）。 */
  fieldNames?: { key?: string; children?: string };
  /** 包装器扩展（Cascader 用它挂 `pathKeyEntities`）。 */
  initWrapper?: (wrapper: Wrapper) => Wrapper | undefined;
  /** 每个实体构造后的钩子（Cascader 用它把 key 覆写成 pathKey）。 */
  processEntity?: (entity: DataEntity, wrapper: Wrapper) => void;
  /** 全部处理完的钩子。 */
  onProcessFinished?: (wrapper: Wrapper) => void;
}

const DEFAULT_FIELD_NAMES = { key: 'key', children: 'children' };

function getPosition(level: string | number, index: number): string {
  return `${level}-${index}`;
}

function getKey(key: unknown, pos: string): string {
  return key !== null && key !== undefined ? String(key) : pos;
}

/**
 * 遍历嵌套数据（广度优先按层级展开，与上游同序）。
 *
 * ⚠️ 上游 `traverseDataNodes` 的 `nodes` 是**路径链**（根→当前），不是 children ——
 *    Cascader 的 typed value path 依赖完整的 nodes 路径。
 */
export function traverseDataNodes(
  dataNodes: Record<string, unknown>[],
  callback: (item: {
    node: Record<string, unknown>;
    index: number;
    pos: string;
    key: string;
    parentPos: string;
    level: number;
    nodes: Record<string, unknown>[];
  }) => void,
  config: ConvertConfig = {},
): void {
  const { key: fieldKey, children: fieldChildren } = {
    ...DEFAULT_FIELD_NAMES,
    ...(config.fieldNames ?? {}),
  };

  /**
   * @param level 本节点的 level；根调用传 **0** ⇒ 第一层节点的 level 为 0
   *              （rc-tree 的 level 从 0 起算）。⚠️ 不能用 `parentLevel + 1`
   *              的写法——虚拟根会把 -1 加成 0 再传给子，整体偏移一层。
   */
  function processNode(
    node: Record<string, unknown> | null,
    index: number,
    parent: { pos: string; level: number } | null,
    pathNodes: Record<string, unknown>[],
    level: number,
  ): void {
    const mergedParent = parent as { pos: string; level: number } | undefined;
    const children = (node ? node[fieldChildren] : dataNodes) as
      | Record<string, unknown>[]
      | undefined;
    // biome-ignore lint/style/noNonNullAssertion: node 非空时 mergedParent 必由调用方给出（pos/parentPos 都从它派生）
    const pos = node ? getPosition(mergedParent!.pos, index) : '0';
    const connectNodes = node ? [...pathNodes, node] : [];

    if (node) {
      callback({
        node,
        index,
        pos,
        key: getKey(node[fieldKey], pos),
        // biome-ignore lint/style/noNonNullAssertion: 同上 —— 这一支只在 node 非空时执行
        parentPos: mergedParent!.pos,
        level,
        nodes: connectNodes,
      });
    }

    (children ?? []).forEach((child, childIndex) => {
      processNode(child, childIndex, { pos, level }, connectNodes, level + 1);
    });
  }

  // ⚠️ 虚拟根的 level 是 **-1**：递归里 `level + 1` 后第一层节点的 level 才是 0
  //    （rc-tree 的 level 从 0 起算；传 0 会让整棵树偏移一层，conduct 的层级分组全错）
  processNode(null, 0, { pos: '0', level: -1 }, [], -1);
}

/**
 * 摊平嵌套数据为实体表。
 *
 * 与上游同构：同时产出 `posEntities` 与 `keyEntities`，`initWrapper` 可扩展包装器，
 * `processEntity` 在每个实体建好后回调（Cascader 借此把 `entity.key` 覆写成 pathKey）。
 */
export function convertDataToEntities(
  dataNodes: Record<string, unknown>[],
  config: ConvertConfig = {},
): Wrapper {
  const posEntities: Record<string, DataEntity> = {};
  const keyEntities: Record<string, DataEntity> = {};
  let wrapper: Wrapper = { posEntities, keyEntities };
  if (config.initWrapper) {
    wrapper = config.initWrapper(wrapper) ?? wrapper;
  }

  traverseDataNodes(
    dataNodes,
    (item) => {
      const { node, index, pos, key, parentPos, level, nodes } = item;
      const entity: DataEntity = { node, nodes, index, key, pos, level };
      const mergedKey = getKey(key, pos);

      Object.defineProperty(posEntities, pos, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });
      Object.defineProperty(keyEntities, mergedKey, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });

      entity.parent = Object.hasOwn(posEntities, parentPos) ? posEntities[parentPos] : undefined;
      if (entity.parent) {
        entity.parent.children = entity.parent.children || [];
        entity.parent.children.push(entity);
      }

      config.processEntity?.(entity, wrapper);
    },
    config,
  );

  config.onProcessFinished?.(wrapper);
  return wrapper;
}

// ================================ conduct ================================

export interface ConductResult {
  checkedKeys: string[];
  halfCheckedKeys: string[];
}

/** 上游 `isCheckDisabled`：`disabled` / `disableCheckbox` / `checkable === false`。 */
function isCheckDisabled(node: Record<string, unknown> | undefined): boolean {
  if (!node) return false;
  const { disabled, disableCheckbox, checkable } = node as {
    disabled?: boolean;
    disableCheckbox?: boolean;
    checkable?: boolean;
  };
  return !!(disabled || disableCheckbox) || checkable === false;
}

function removeFromCheckedKeys(
  halfCheckedKeys: Set<string>,
  checkedKeys: Set<string>,
): Set<string> {
  const filtered = new Set<string>();
  halfCheckedKeys.forEach((key) => {
    if (!checkedKeys.has(key)) filtered.add(key);
  });
  return filtered;
}

/** 按层级分组（上游 `conductCheck` 的第一步）。 */
function groupByLevel(keyEntities: Record<string, DataEntity>) {
  const levelEntities = new Map<number, Set<DataEntity>>();
  let maxLevel = 0;
  Object.keys(keyEntities).forEach((key) => {
    // noUncheckedIndexedAccess：索引访问可能 undefined（key 来自 Object.keys，防御式收窄）
    const entity = Object.hasOwn(keyEntities, key) ? keyEntities[key] : undefined;
    if (!entity) return;
    const { level } = entity;
    // ⚠️ 用局部变量接住（`get(...)!` 消不掉，且 `Map.get` 的返回类型永远是 `T | undefined`）
    let levelSet = levelEntities.get(level);
    if (!levelSet) {
      levelSet = new Set();
      levelEntities.set(level, levelSet);
    }
    levelSet.add(entity);
    maxLevel = Math.max(maxLevel, level);
  });
  return { levelEntities, maxLevel };
}

/** 自底向上：父的全部（非禁用）子是否都选中 / 部分选中。 */
function conductParent(
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  checkedKeys: Set<string>,
  halfCheckedKeys: Set<string>,
  getDisabled: (node: Record<string, unknown>) => boolean,
  onAllChecked: (parentKey: string) => void,
  onPartialChecked: (parentKey: string) => void,
): void {
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { node } = entity;
      const parent = entity.parent;
      if (!parent || getDisabled(node) || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const checked = checkedKeys.has(key);
          if (allChecked && !checked) allChecked = false;
          if (!partialChecked && (checked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (allChecked) onAllChecked(parent.key);
      if (partialChecked) onPartialChecked(parent.key);
      visitedKeys.add(parent.key);
    });
  }
}

function fillConductCheck(
  keys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  const halfCheckedKeys = new Set<string>();

  // 自顶向下：父选中 ⇒ 补子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (checkedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.add(childEntity.key);
          });
      }
    });
  }

  // 自底向上：子全选 ⇒ 补父；部分 ⇒ half
  conductParent(
    levelEntities,
    maxLevel,
    checkedKeys,
    halfCheckedKeys,
    getDisabled,
    (parentKey) => checkedKeys.add(parentKey),
    (parentKey) => halfCheckedKeys.add(parentKey),
  );

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

function cleanConductCheck(
  keys: Set<string>,
  halfKeys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  let halfCheckedKeys = new Set(halfKeys);

  // 自顶向下：未选中且非半选 ⇒ 清掉子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (!checkedKeys.has(key) && !halfCheckedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.delete(childEntity.key);
          });
      }
    });
  }

  // ⚠️ 自底向上必须**单遍**：`delete(parent.key)` 会立刻影响更高一层的判定
  //    （上游就是同一轮里先算 allChecked / partialChecked 再改 checkedKeys）。
  //    拆成两遍会让高层读到「本该删掉的父」，half 集合偏大。
  halfCheckedKeys = new Set<string>();
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { parent, node } = entity;
      if (getDisabled(node) || !parent || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const isChecked = checkedKeys.has(key);
          if (allChecked && !isChecked) allChecked = false;
          if (!partialChecked && (isChecked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (!allChecked) checkedKeys.delete(parent.key);
      if (partialChecked) halfCheckedKeys.add(parent.key);
      visitedKeys.add(parent.key);
    });
  }

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

/**
 * 勾选传导。
 *
 * @param keyList 当前 key 列表
 * @param checked `true` = fill（补全）；`{ checked: false, halfCheckedKeys }` = clean（清理）
 * @param keyEntities `convertDataToEntities` 产出的 `keyEntities`
 */
export function conductCheck(
  keyList: string[],
  checked: true | { checked: false; halfCheckedKeys: string[] },
  keyEntities: Record<string, DataEntity>,
  getCheckDisabled?: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const getDisabled = getCheckDisabled ?? isCheckDisabled;

  // 只处理存在的 key（上游会 warning 缺失的 key，本仓静默过滤）
  const keys = new Set(keyList.filter((key) => Object.hasOwn(keyEntities, key)));

  const { levelEntities, maxLevel } = groupByLevel(keyEntities);

  if (checked === true) {
    return fillConductCheck(keys, levelEntities, maxLevel, getDisabled);
  }
  return cleanConductCheck(
    keys,
    new Set(checked.halfCheckedKeys),
    levelEntities,
    maxLevel,
    getDisabled,
  );
}
```

## 自定义触发器 (custom-trigger)

默认插槽内容会作为 `raw trigger` 替代内建输入框；这里用带图标和当前标签的按钮作为触发器，选择结果会实时回写到按钮文字。

### custom-trigger.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 custom-trigger demo：默认插槽内容作为 raw trigger
import { EnvironmentOutlined } from '@apollo-design/icons';
import { Button, Cascader, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';
import type { CascaderOutputValue } from '../interface';

const value = ref<CascaderOutputValue>(['zhejiang', 'hangzhou']);

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

const labels: Record<string, string> = {
  zhejiang: '浙江',
  hangzhou: '杭州',
  ningbo: '宁波',
  jiangsu: '江苏',
  nanjing: '南京',
};

const display = computed(() => {
  if (!value.value.length) return '请选择地区';
  return value.value.map((item) => labels[String(item)] ?? item).join(' / ');
});
</script>

<template>
  <div>
    <Cascader v-model:value="value" :options="options">
      <Button type="primary" ghost :icon="EnvironmentOutlined">{{ display }}</Button>
    </Cascader>

    <div style="margin-top: 16px">
      <Tag color="blue">当前选择</Tag>
      <span>{{ display }}</span>
    </div>

    <p style="margin-bottom: 0">
      默认插槽内容作为触发器；点击按钮展开级联面板，选择后按钮文字同步更新。
    </p>
  </div>
</template>
```

### ../interface.ts

```ts
import type { CSSProperties, VNode, VNodeChild } from 'vue';
import type { SemanticInput } from '../_internal/use-merge-semantic';
import type { SizeType } from '../config-provider/size-context';
import type { SelectCommonPlacement, SelectSlots, SelectVariant } from '../select/interface';
import type { SearchConfig } from './hooks/search';
import type { BaseOptionType, FieldNames, RawValue, ShowCheckedStrategy, ValueCell } from './utils';

export type CascaderValue = RawValue | ValueCell[];
export type CascaderOutputValue = ValueCell | ValueCell[];
export type CascaderSelectedOptions = (BaseOptionType | null)[] | (BaseOptionType | null)[][];
export type CascaderSearchConfig = Omit<SearchConfig, 'render' | 'searchValue' | 'onSearch'>;
export interface CascaderSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: { root?: string; list?: string; listItem?: string };
}
export interface CascaderSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: { root?: CSSProperties; list?: CSSProperties; listItem?: CSSProperties };
}
export interface CascaderPanelProps {
  prefixCls?: string;
  options?: BaseOptionType[];
  value?: CascaderValue;
  defaultValue?: CascaderValue;
  multiple?: boolean;
  fieldNames?: FieldNames;
  changeOnSelect?: boolean;
  showCheckedStrategy?: ShowCheckedStrategy;
  loadData?: (selectedOptions: BaseOptionType[]) => void | Promise<void>;
  expandTrigger?: 'click' | 'hover';
  expandIcon?: VNodeChild;
  loadingIcon?: VNodeChild;
  direction?: 'ltr' | 'rtl';
  notFoundContent?: VNodeChild;
  disabled?: boolean;
  popupMenuColumnStyle?: CSSProperties;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderPanelProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderPanelProps>;
  'onUpdate:value'?: (value: CascaderOutputValue) => void;
  onChange?: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
}
export interface CascaderProps extends Omit<CascaderPanelProps, 'classNames' | 'styles'> {
  id?: string;
  checkable?: boolean;
  size?: SizeType;
  loading?: boolean;
  variant?: SelectVariant;
  bordered?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild };
  clearIcon?: VNodeChild;
  removeIcon?: VNodeChild;
  suffixIcon?: VNodeChild;
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  showSearch?: boolean | CascaderSearchConfig;
  searchValue?: string;
  autoClearSearchValue?: boolean;
  placeholder?: VNodeChild;
  popupClassName?: string;
  dropdownClassName?: string;
  popupStyle?: CSSProperties;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement;
  status?: 'error' | 'warning';
  maxTagCount?: number;
  maxTagTextLength?: number;
  maxTagPlaceholder?: VNodeChild;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderProps>;
  'onUpdate:open'?: (open: boolean) => void;
  'onUpdate:searchValue'?: (value: string) => void;
  onOpenChange?: (open: boolean) => void;
  onSearch?: (value: string) => void;
  onFocus?: (event: FocusEvent) => void;
  onBlur?: (event: FocusEvent) => void;
  onClear?: () => void;
  onPopupScroll?: (event: Event) => void;
  onKeydown?: (event: KeyboardEvent) => void;
  onKeyup?: (event: KeyboardEvent) => void;
  onMousedown?: (event: MouseEvent) => void;
}
export interface CascaderEmits {
  'update:value': (value: CascaderOutputValue) => void;
  change: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
  'update:open': (open: boolean) => void;
  openChange: (open: boolean) => void;
  'update:searchValue': (value: string) => void;
  search: (value: string) => void;
  focus: (event: FocusEvent) => void;
  blur: (event: FocusEvent) => void;
  clear: () => void;
  popupScroll: (event: Event) => void;
  keydown: (event: KeyboardEvent) => void;
  keyup: (event: KeyboardEvent) => void;
  mousedown: (event: MouseEvent) => void;
}
export interface CascaderOptionSlots {
  optionRender?: (scope: { option: BaseOptionType; pathOptions: BaseOptionType[] }) => VNodeChild;
  searchRender?: (scope: {
    inputValue: string;
    pathOptions: BaseOptionType[];
    fieldNames: FieldNames;
  }) => VNodeChild;
  expandIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
  loadingIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
}
export interface CascaderPanelSlots extends CascaderOptionSlots {
  notFoundContent?: () => VNodeChild;
}
export interface CascaderSlots extends CascaderPanelSlots {
  default?: () => VNodeChild;
  placeholder?: () => VNodeChild;
  displayRender?: (scope: {
    labels: VNodeChild[];
    selectedOptions: (BaseOptionType | null)[];
  }) => VNodeChild;
  suffixIcon?: SelectSlots['suffixIcon'];
  searchIcon?: SelectSlots['suffixIcon'];
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  maxTagPlaceholder?: (scope: {
    omittedValues: { value: ValueCell; label: VNodeChild; disabled?: boolean }[];
  }) => VNodeChild;
  popupRender?: (scope: { menu: VNode }) => VNodeChild;
}
export interface CascaderRef {
  readonly nativeElement: HTMLElement | null;
  focus: (options?: FocusOptions) => void;
  blur: () => void;
}
```

### ../../_internal/use-merge-semantic.ts

````ts
/**
 * 语义化 `classNames` / `styles` 的合并。
 *
 * 契约来源：antd 6.6.4 的 `es/_util/hooks/useMergeSemantic/index.js`（**逐条对齐**）。
 *
 * 为什么单独抽出来：72 个组件里有 60 多个都有 `classNames` / `styles`，合并语义
 * 一旦不一致，就会出现「Button 的覆盖优先级和 Empty 不一样」这类只有用户才会发现的问题。
 * 所以合并规则集中在这里，组件只声明「合并哪些来源、按什么顺序」。
 *
 * ── 与 antd 的对应关系（合并顺序是契约，不能改）────────────────────────────────
 *
 * ```
 * // antd（Empty）
 * const [mergedClassNames, mergedStyles] = useMergeSemantic(
 *   [contextClassNames, classNames],                          // classNamesList
 *   [contextStyles, contextStyleRoot, styles, styleRoot],     // stylesList
 *   { props },
 * );
 * ```
 *
 * 其中 `contextStyleRoot = useSemanticRootStyle(contextStyle)`、`styleRoot = useSemanticRootStyle(style)`，
 * 即把 `style` 这个平铺的 prop 包成 `{ root: style }` 再进合并。
 *
 * 三条必须逐字保留的判据：
 *   1. **classNames 是「拼接」不是「覆盖」** —— `clsx(acc[key], curVal)`，同名键会连起来。
 *   2. **styles 是「逐键浅合并、后者胜」** —— 与 classNames 不同，这里不是拼接。
 *   3. **`style` prop 排在 `styles.root` 之后** —— 所以 `style` 会**覆盖** `styles.root`。
 *      这条最反直觉，也最容易被「顺手改成更合理的顺序」。
 *
 * ── 函数式变体（裁决 `empty-semantic-fn` = B：支持）───────────────────────────
 *
 * antd 允许传 `(info: { props }) => 对象`。我们在 `resolveSemantic` 里逐字对应：
 * 判据是 `isFunction(value) ? value(info) : value`，**没有**额外的「只在需要时求值」优化
 * —— 那种优化会让函数式与对象式的行为出现差异。
 *
 * ── `schema`（嵌套语义槽）—— **2026-10-03 补齐** ──────────────────────────────
 *
 * antd 的第四参 `schema` 用 `_default` 把「字符串形态的嵌套键」落到指定子槽
 * （`classNames.popup = 'x'` ≡ `classNames.popup = { root: 'x' }`），并在最后用
 * `fillObjectBySchema` 保证嵌套键**恒为对象**。
 *
 * 本仓此前没有它，用「只要有一侧是对象就递归」绕过 —— 那在**字符串与对象混用**时
 * 会产垃圾键（`Object.keys('x')`）。antd 6.6.4 里 **9 个组件**传了 schema
 * （`select` / `cascader` / `color-picker` / `menu` / `tabs` / `image` / `splitter` /
 * `input.Search` / `table`），Table 是第一个**真的需要**它的（`body.cell` / `header.cell`）。
 *
 * ⚠️ **两条语义并存、不能合并**：不给 schema 时保持本仓既有行为（7 个消费者钉住它），
 *    给了 schema 才走 antd 的 `mergeClassNamesBySchema`。
 *    判据见 `__tests__/use-merge-semantic.test.ts` 的「反向哨兵」那一条。
 *
 * ── 这个模块没有证明什么 ──────────────────────────────────────────────────────
 *   - 没证明各组件的**合并顺序声明**是对的。本模块只保证「给定顺序，合并结果正确」；
 *     顺序本身由各组件的 compat 用例与 antd 对照（Empty 见 `__tests__/semantic.test.ts`）。
 *   - 没证明**所有该传 schema 的组件都传了**。schema 档 2026-10-03 实现，
 *     select / cascader / color-picker / tabs / image（×2）/ splitter 已补第四参；
 *     menu 无语义通道、`input.Search` 未实现（见 `docs/KNOWN-ISSUES.md` §2 留痕）。
 *
 *   ⚠️ 无 schema 的宽松路径（`mergeClassNames`）**仍在服务既有消费者**：它在
 *     「字符串 + 对象混用」时会产垃圾键（`Object.keys('x')`）。这条**曾**登记在
 *     `docs/KNOWN-ISSUES.md`，该文件的 §1 已于 2026-10-07 清零、登记项转入 §2 的
 *     「已修 / 已裁决」；但宽松路径本身**未改**（7 个既有消费者的用例钉住它）。
 *     若将来统一到 schema 档，需同步改这 7 处并重跑它们的 L4/L6。
 */

import { isFunction } from '@apollo-design/utils';
import {
  type ComputedRef,
  type CSSProperties,
  computed,
  type MaybeRefOrGetter,
  toValue,
} from 'vue';

/** 函数式语义化拿到的上下文。与 antd 的 `{ props }` 同构。 */
export interface SemanticInfo<P> {
  props: P;
}

/** 对象式或函数式的语义化输入。 */
export type SemanticInput<T, P> = T | ((info: SemanticInfo<P>) => T | undefined);

/** 任意可响应化的输入。普通值、ref、getter 都接受（与 `toValue` 同构）。 */
export type MaybeSource<T> = MaybeRefOrGetter<T>;

/**
 * ⚠️ **刻意不用** `_internal/clsx.ts` 那一份（2026-10-07 核对过）。
 *
 * 这里是**更窄**的语义：只保留字符串，数字 / 数组 / 对象一律丢弃。
 * 而共享层那份会展开数组与对象（`{a:true}` → `'a'`）。语义化 `classNames` 的槽位值
 * 本来就是字符串，宽版本在这里只会把「传错了形态」静默变成一个类名。
 * ⇒ 别为了「消重」把它换成共享版 —— 那份窄语义是有意的。
 */
function clsx(...values: unknown[]): string {
  return values.filter((v) => typeof v === 'string' && v !== '').join(' ');
}

/**
 * 求值一个语义化输入。
 *
 * 与 antd 的 `resolveStyleOrClass(value, info)` 逐字对应 —— 包括
 * **只在 `isFunction` 时求值**这一点：传 `null` / `undefined` 会原样返回，
 * 由下游的 `filter(Boolean)` 丢掉。
 */
export function resolveSemantic<T, P>(
  value: SemanticInput<T, P> | undefined | null,
  info: SemanticInfo<P>,
): T | undefined {
  if (value === undefined || value === null) return undefined;
  return isFunction(value) ? (value as (i: SemanticInfo<P>) => T | undefined)(info) : value;
}

/**
 * 合并 classNames。**拼接**语义：同名键连起来，不覆盖。
 *
 * 与 antd 的 `mergeClassNames(schema, ...classNames)` 在 `schema === undefined` 时等价。
 *
 * ⚠️ 实现里有一次类型断言（`as Record<string, string | undefined>`）。
 *    它**不是**类型漏洞，而是「语义键集合由调用方的泛型决定」这一事实的必然结果：
 *    函数体只做键的遍历与字符串拼接，不认识任何具体键。用 `as any` 才是漏洞，
 *    这里断言到的是精确的中间形态。
 */
export function mergeClassNames<CN extends object>(
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const cur = record[key];
      const prev = acc[key];
      // 嵌套语义对象（如 Select 的 classNames.popup.{root,list,listItem}）递归合并；
      // 叶子值按 clsx 拼接（select 期 AutoComplete 抓出：浅合并在 popup 上丢数据）
      if (isPlainRecord(cur) || isPlainRecord(prev)) {
        acc[key] = mergeClassNames((prev ?? {}) as never, (cur ?? {}) as never);
      } else {
        acc[key] = clsx(prev as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

function isPlainRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// ---------------------------------------------------------------------------
// schema（嵌套语义槽）—— antd `useMergeSemantic` 的第四参
// ---------------------------------------------------------------------------

/**
 * schema 的**键名首字符**集合。
 *
 * 与 antd 的 `ValidChar`（`_util/type.ts:91`）**逐字相同**：**只有小写 a–z**。
 * 这不是「随便写的」—— 它正是让 `_default`（下划线开头）**不落进**索引签名、
 * 从而不与 `{ _default?: string }` 冲突的机制。
 * ⇒ 别「顺手」把大写或下划线加进来（会让 `SemanticSchema` 立刻变成 `never` 交叉）。
 */
type LowerChar =
  | 'a'
  | 'b'
  | 'c'
  | 'd'
  | 'e'
  | 'f'
  | 'g'
  | 'h'
  | 'i'
  | 'j'
  | 'k'
  | 'l'
  | 'm'
  | 'n'
  | 'o'
  | 'p'
  | 'q'
  | 'r'
  | 's'
  | 't'
  | 'u'
  | 'v'
  | 'w'
  | 'x'
  | 'y'
  | 'z';

/**
 * 嵌套语义槽的映射表。与 antd 的 `SemanticSchema` 同构。
 *
 * `_default: 'root'` 的语义（**逐条来自 antd 的 `mergeClassNames`**）：
 *   - 该键收到**普通对象** ⇒ 递归按子 schema 合并；
 *   - 该键收到**非对象**（字符串）⇒ 落到 `acc[key][_default]`（即 `classNames.popup = 'x'`
 *     ≡ `classNames.popup = { root: 'x' }`）；
 *   - **没有** `_default` 的子 schema（如 `image` 的 `placeholder: {}`）⇒ 只保证该键
 *     恒为对象（`fillObjectBySchema` 的 `||= {}`），不做字符串转换。
 */
export type SemanticSchema = { _default?: string } & {
  [key: `${LowerChar}${string}`]: SemanticSchema;
};

/**
 * 按**任意字符串键**读子 schema。
 *
 * ⚠️ 必须走这层 cast：`SemanticSchema` 的索引签名是 `` `${LowerChar}${string}` ``
 *    （antd 的 `ValidChar` 口径，见上面的注释），而 `Object.keys()` 给的是 `string`
 *    ⇒ 直接写 `schema[key]` 会 **TS7053**。这里的 cast 是**诚实的**：运行时 schema 的键
 *    本来就来自调用方写的对象字面量，`Object.keys` 拿到的正是那些键。
 */
function subSchema(schema: SemanticSchema, key: string): SemanticSchema | undefined {
  return (schema as Record<string, SemanticSchema | undefined>)[key];
}

/**
 * 按 schema 补齐对象结构（antd `fillObjectBySchema` 逐字）。
 *
 * 两条判据：
 *   ① `_default` 键 ⇒ `newObj[key] ||= {}`（保证**至少是空对象**，不会残留 `undefined`）；
 *   ② 其余子 schema ⇒ 递归（空 schema `{}` 会让该键变成 `{}`）。
 */
export function fillObjectBySchema(
  obj: Record<string, unknown> | undefined,
  schema: SemanticSchema,
): Record<string, unknown> {
  const newObj: Record<string, unknown> = { ...(obj ?? {}) };
  for (const key of Object.keys(schema)) {
    if (subSchema(schema, key)?._default) {
      newObj[key] ||= {};
    } else {
      newObj[key] = fillObjectBySchema(
        newObj[key] as Record<string, unknown> | undefined,
        subSchema(schema, key) as SemanticSchema,
      );
    }
  }
  return newObj;
}

/**
 * **带 schema** 的 classNames 合并（antd `mergeClassNames(schema, ...classNames)` 逐字）。
 *
 * ⚠️ 与下面**无 schema** 的 `mergeClassNames` 是**两条不同的语义**，不要合并：
 *    - 无 schema：只要有一侧是对象就**递归**（本仓在 select/auto-complete 期加的行为，
 *      比 antd 更宽松，且已被 7 个组件的既有用例钉住）；
 *    - 有 schema：**只有 schema 声明过的键**才特殊处理，其余键一律 `clsx` 平铺（antd 语义）。
 *
 *    两者的差别在「字符串 vs 对象混用」时可见：
 *      `classNames: { popup: 'x' }` 与 `{ popup: { root: 'y' } }` 两个来源
 *      —— schema 版给 `popup.root = 'x y'`（正确）；无 schema 版会把 `'x'` 当对象递归
 *      （`Object.keys('x')` ⇒ 垃圾键）。这正是 antd 需要 `_default` 的原因。
 */
export function mergeClassNamesBySchema<CN extends object>(
  schema: SemanticSchema,
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const keySchema = subSchema(schema, key);
      const cur = record[key];
      if (keySchema) {
        if (isPlainRecord(cur)) {
          acc[key] = mergeClassNamesBySchema(keySchema, (acc[key] ?? {}) as never, cur as never);
        } else {
          const defaultField = keySchema._default;
          if (defaultField) {
            const target = (acc[key] ?? {}) as Record<string, unknown>;
            target[defaultField] = clsx(
              target[defaultField] as string | undefined,
              cur as string | undefined,
            );
            acc[key] = target;
          }
        }
      } else {
        acc[key] = clsx(acc[key] as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

/**
 * 合并 styles。**逐键浅合并、后者胜** —— 注意与 classNames 的语义不同。
 *
 * 与 antd 的 `mergeStyles(...styles)` 等价。断言理由同 `mergeClassNames`。
 */
export function mergeStyles<ST extends object>(
  ...sources: readonly (Partial<ST> | undefined)[]
): Partial<ST> {
  const acc: Record<string, CSSProperties | undefined> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, CSSProperties | string | undefined>;
    for (const key of Object.keys(record)) {
      // 🚨 **叶子可能是 CSS 字符串**（Vue 的 `style` attr 允许字符串，而 `attrs.style`
      //    会经 `semanticRootStyle` 进到这里）。直接展开字符串会得到
      //    `{ 0: 'w', 1: 'i', … }` ⇒ Vue 的 `setStyle` 抛
      //    `'set' on proxy: trap returned falsish for property '0'`。
      acc[key] = { ...acc[key], ...normalizeStyleValue(record[key]) };
    }
  }
  return acc as Partial<ST>;
}

/**
 * `'width: 240px; color: red'` → `{ width: '240px', color: 'red' }`。
 *
 * ⚠️ 不引入 `@vue/shared` 的 `parseStringStyle`：它是 `vue` 的**传递依赖**，
 *    直接 import 属于幻影依赖（R7 的精神）。这里只需要支持 `;` 分隔的声明段，
 *    与 Vue 自己的实现判据一致（空段 / 无冒号的段跳过）。
 */
function parseStyleString(text: string): CSSProperties {
  const out: Record<string, string> = {};
  for (const part of text.split(';')) {
    const index = part.indexOf(':');
    if (index < 0) continue;
    const name = part.slice(0, index).trim();
    if (!name) continue;
    out[name] = part.slice(index + 1).trim();
  }
  return out as CSSProperties;
}

/** 样式叶子归一：字符串解析成对象，其余原样。 */
function normalizeStyleValue(value: CSSProperties | string | undefined): CSSProperties | undefined {
  if (typeof value === 'string') {
    return parseStyleString(value);
  }
  return value;
}

/**
 * 把平铺的 `style` 包成 `{ root: style }`。
 *
 * 与 antd 的 `useSemanticRootStyle(style, key = 'root')` 等价 —— 包括
 * 「`style` 为空时返回 `undefined` 而不是 `{ root: undefined }`」这一点：
 * 后者会让 `mergeStyles` 多产出一个 `root` 键，进而在 DOM 上多出一个空的 `style=""`。
 */
export function semanticRootStyle(
  style: CSSProperties | string | undefined,
  key = 'root',
): Record<string, CSSProperties> | undefined {
  if (!style) {
    return undefined;
  }
  // 🚨 `style` 可能是 **CSS 字符串**（`<Input style="width: 240px" />` —— Vue 的 `style`
  //    attr 两种形态都合法）。必须在这里解析成对象，否则下游 `mergeStyles` 的
  //    对象展开会把它拆成 `{ 0: 'w', … }`（Issue #7.1 实测）。
  return { [key]: typeof style === 'string' ? parseStyleString(style) : style };
}

/**
 * 把「可能为空的样式」转成可以直接 `v-bind` 的属性对象。
 *
 * 空样式返回 `{}`（**连 `style` 这个键都没有**），非空返回 `{ style }`。
 *
 * ── 为什么必须做这一步（2026-09-18，empty 实测）──────────────────────────────
 *
 * `mergeStyles()` 的返回值**恒**是对象（可能是 `{}`）。直接绑 `:style` 时：
 *
 * | 渲染路径 | 结果 |
 * |---|---|
 * | 客户端 | `patchStyle` 会把空样式移除 —— 没有 `style` 属性 ✓ |
 * | **SSR** | `ssrRenderAttrs` 对 `style` 键是**无条件**输出的 ⇒ 渲染出 `style=""` ✗ |
 *
 * React（antd）在样式为空时**不输出该属性**。所以 SSR 产物会与上游有差异，
 * 而且每个元素多 9 字节 —— 72 个组件 × 多层结构累积起来是可观的体积。
 *
 * 实测：Empty 一层就有 3 个元素带 `style=""`；改成 `v-bind="styleAttrs(x)"` 后归零。
 *
 * ⚠️ 这个差异 L4 **测不出来** —— 投影会把「没有 style 属性」与 `style=""`
 *    都归一化成空串（`(node.style ?? []).join(';')` 两边都是 `''`）。
 *    它是被渲染 SSR 预览页时肉眼发现的，所以既有 L1 断言也有这里。
 *
 * ⚠️ 所有用 `useMergeSemantic` 的组件都应该这样绑样式，而不是 `:style="mergedStyles.x"`。
 */
export function styleAttrs(style: CSSProperties | undefined): { style?: CSSProperties } {
  if (!style) return {};
  const record = style as Record<string, unknown>;
  for (const key of Object.keys(record)) {
    if (record[key] !== undefined) return { style };
  }
  return {};
}

export interface UseMergeSemanticResult<CN extends object, ST extends object> {
  classNames: ComputedRef<Partial<CN>>;
  styles: ComputedRef<Partial<ST>>;
}

/**
 * 响应式版本的 `useMergeSemantic`。
 *
 * 与 antd 的差别只有一处、且是平台差异（PLATFORM）：antd 每次渲染都重跑一遍合并，
 * 我们用 `computed` 缓存 —— 语义相同，但**依赖必须可追踪**，所以来源要用
 * `() => value` 的形式传，而不是先取值再传。
 *
 * @param classNamesSources 按优先级从低到高排列（后者拼接在前者之后）
 * @param stylesSources 按优先级从低到高排列（后者覆盖前者）
 * @param props 传给函数式变体的 `info.props`。**可以是 getter / ref** ——
 *   函数式变体每次重算都要看到**当前** props。传 `mergedProps.value` 那种
 *   setup 期快照会让 `disabled` / `size` / `variant` 变化后函数式仍按旧值计算
 *   （Issue #3.2）。裸对象仍然可用（`toValue` 原样返回）。
 * @param schema **嵌套语义槽**的映射表（antd 第四参）。给了它就会：
 *   ① classNames 走 `mergeClassNamesBySchema`（`_default` 的字符串→对象转换）；
 *   ② 两个结果都过一遍 `fillObjectBySchema`（保证嵌套键恒为对象）。
 *   ⚠️ 不给时**保持本仓既有行为**（无 schema 的递归合并）—— 7 个既有消费者不受影响。
 */
export function useMergeSemantic<P extends object, CN extends object, ST extends object>(
  classNamesSources: readonly MaybeSource<SemanticInput<Partial<CN>, P> | undefined>[],
  stylesSources: readonly MaybeSource<SemanticInput<Partial<ST>, P> | undefined>[],
  props: MaybeRefOrGetter<P>,
  schema?: SemanticSchema,
): UseMergeSemanticResult<CN, ST> {
  // ⚠️ `info` 必须在**每次重算时**新建，且 `props` 要在 computed 内 `toValue` ——
  //    在 setup 期建一次会把首帧的 props 快照焊死（Issue #3.2）。
  const classNames = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = classNamesSources.map((source) =>
      resolveSemantic<Partial<CN>, P>(toValue(source), info),
    );
    const merged = schema
      ? mergeClassNamesBySchema<CN>(schema, ...resolved)
      : mergeClassNames<CN>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<CN>;
  });

  const styles = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = stylesSources.map((source) =>
      resolveSemantic<Partial<ST>, P>(toValue(source), info),
    );
    const merged = mergeStyles<ST>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<ST>;
  });

  return { classNames, styles };
}
````

### ../../config-provider/size-context.ts

````ts
/**
 * `SizeContext` —— 组件尺寸。
 *
 * 契约来源：antd 6.6.4 的 `es/config-provider/SizeContext.tsx` + `hooks/useSize.ts`。
 *
 * ── 为什么它是**独立 context** 而不是 ConfigContext 的一个字段 ──────────────────
 *
 * antd 把它拆出去是为了「`componentSize` 变化时只重渲染读尺寸的组件」。
 * 本项目的理由更硬：`ConfigContextValue` 是**一个**响应式对象，任何字段变化都会
 * 触发所有读它的 `computed` 重算；而尺寸是被最多组件读的字段之一，独立出来能明显
 * 收窄依赖面。形态上也与 antd 对齐（便于迁移）。
 */

import { type ComputedRef, computed, type InjectionKey, inject } from 'vue';

/**
 * 尺寸。
 *
 * ⚠️ `'medium'` 与 `'middle'` **两个都要**：antd 6 起 `'medium'` 是推荐写法，
 * `'middle'` 仍是默认值且未移除（上游注释：`middle is deprecated and will be removed
 * in v7`）。`COMPONENT-RULES.md` §4 要求枚举值与 antd 一致 ⇒ 不裁剪成 `'medium'`。
 */
export type SizeType = 'small' | 'medium' | 'middle' | 'large';

/**
 * 注入键。
 *
 * 值是 `ComputedRef` 而不是裸值 —— 这样 `useSize` 在 `computed` 里读 `.value`
 * 会被追踪，`componentSize` 变化能传导到下游（对齐 antd 的 context 更新）。
 */
export const sizeContextKey: InjectionKey<ComputedRef<SizeType | undefined>> =
  Symbol('apolloSizeContext');

/**
 * 读取组件尺寸，与自己的 prop 合并。与 antd 的 `useSize` 逐字对应。
 *
 * 四条判据（逐条来自 `hooks/useSize.ts`）：
 *   1. `!customSize` ⇒ 用 context（⚠️ 真值判据：`0` / `''` 也走这一支）。
 *   2. `customSize` 是字符串 ⇒ `customSize ?? size`（字符串恒真，等价于直接返回）。
 *   3. `customSize` 是函数 ⇒ `customSize(size)`。
 *   4. 其余（数字 / 对象）⇒ 用 context。
 *
 * @example
 * ```ts
 * const mergedSize = useSize(props.size);   // ComputedRef<SizeType | undefined>
 * ```
 */
export function useSize<T extends string | number | undefined | object>(
  customSize?: T | ((ctxSize: SizeType | undefined) => T),
): ComputedRef<T | SizeType | undefined> {
  const injected = inject(sizeContextKey, undefined);

  return computed(() => {
    const ctxSize = injected?.value;

    if (!customSize) return ctxSize;

    if (typeof customSize === 'string') return customSize ?? ctxSize;

    if (typeof customSize === 'function') {
      return (customSize as (ctxSize: SizeType | undefined) => T)(ctxSize);
    }

    return ctxSize;
  });
}
````

### ../../select/interface.ts

```ts
/** Public Vue contracts for Select and its option data. */

import type { CSSProperties, VNodeChild } from 'vue';
import type { SizeType } from '../config-provider/size-context';

// ---------------------------------------------------------------------------
// 基础值类型
// ---------------------------------------------------------------------------

export type RawValueType = string | number;

/** antd 的 `SelectValue`。 */
export type SelectValue =
  | RawValueType
  | RawValueType[]
  | LabeledValue
  | LabeledValue[]
  | null
  | undefined;

/** antd 的 `LabeledValue`（labelInValue 的输出形态）。 */
export interface LabeledValue {
  key?: RawValueType;
  value: RawValueType;
  label?: unknown;
}

/** rc 的内部形态（`labelInValue` 的中间表示）。 */
export interface LabelInValueType {
  label?: unknown;
  value: RawValueType;
  key?: RawValueType;
  disabled?: boolean;
  title?: string;
}

export interface BaseOptionType {
  disabled?: boolean;
  className?: string;
  style?: CSSProperties;
  title?: string;
  [name: string]: unknown;
}

export interface DefaultOptionType extends BaseOptionType {
  label?: unknown;
  value?: RawValueType | null;
  children?: Omit<DefaultOptionType, 'children'>[];
  options?: DefaultOptionType[];
}

export type SelectOptionType = BaseOptionType | DefaultOptionType;

/** antd `OptionProps`（`Select.Option` / `Select.OptGroup`，deprecated 但保留）。 */
export interface OptionProps extends BaseOptionType {
  value?: RawValueType | null;
  children?: unknown;
}

export interface OptGroupProps extends BaseOptionType {
  label?: unknown;
  children?: unknown;
}

// ---------------------------------------------------------------------------
// 模式 / 尺寸 / 状态
// ---------------------------------------------------------------------------

/**
 * 公开模式只有 `multiple` / `tags` —— antd 把 `mode="combobox"` 吞成单选
 * （`index.tsx` 的 `mode` memo），只有 `SECRET_COMBOBOX_MODE_DO_NOT_USE` 才真走
 * combobox（AutoComplete 用）。内核实现 combobox 分支，公开类型不声明。
 */
export type SelectMode = 'multiple' | 'tags';

/** 内核模式（engine 内部用）。 */
export type InternalSelectMode = SelectMode | 'combobox';

/**
 * 尺寸。**直接别名到 `config-provider` 的 `SizeType`**（`'small' | 'medium' | 'middle' | 'large'`）。
 *
 * 上游 `SelectProps.size` 就是 `SizeType`；此前手抄成 `'small' | 'middle' | 'large'`
 * 漏了 `medium`（运行时 `useSize` 是吃 `SizeType` 的 ⇒ 类型比运行时窄，Issue #4.3）。
 */
export type SelectSize = SizeType;

export type SelectVariant = 'outlined' | 'borderless' | 'filled' | 'underlined';

export type SelectStatus = 'error' | 'warning' | 'success' | 'validating';

/** antd `SelectCommonPlacement`（`_util/motion.ts` 的 4 值）。 */
export type SelectCommonPlacement = 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight';

export type SelectDirection = 'ltr' | 'rtl';

// ---------------------------------------------------------------------------
// 搜索配置
// ---------------------------------------------------------------------------

export type FilterFunc<OptionType> = (inputValue: string, option: OptionType) => boolean;

export interface SearchConfig<OptionType = DefaultOptionType> {
  autoClearSearchValue?: boolean;
  filterOption?: boolean | FilterFunc<OptionType>;
  filterSort?: (optionA: OptionType, optionB: OptionType, info: { searchValue: string }) => number;
  optionFilterProp?: string | string[];
}

export type SelectSearchConfig = SearchConfig<DefaultOptionType>;

// ---------------------------------------------------------------------------
// 语义槽（classNames / styles）
// ---------------------------------------------------------------------------

export interface SelectSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: {
    root?: string;
    listItem?: string;
    list?: string;
  };
}

export interface SelectSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: {
    root?: CSSProperties;
    listItem?: CSSProperties;
    list?: CSSProperties;
  };
}

export interface FieldNames {
  value?: string;
  label?: string;
  groupLabel?: string;
  options?: string;
}

// ---------------------------------------------------------------------------
// Engine content function types; public component content uses slots.
// ---------------------------------------------------------------------------

/** `FlattenOptionData`（rc `interface.d.ts`）。 */
export interface FlattenOptionData<OptionType = DefaultOptionType> {
  label?: unknown;
  data: OptionType;
  key: string | number;
  value?: RawValueType;
  groupOption?: boolean;
  group?: boolean;
}

/** 选择器里一个已选值的展示形态（rc `DisplayValueType`）。 */
export interface DisplayValueType {
  key?: string | number;
  value?: RawValueType;
  label?: unknown;
  title?: unknown;
  disabled?: boolean;
  index?: number;
}

/** `tagRender` 的入参（rc `CustomTagProps`）。 */
export interface CustomTagProps {
  label?: unknown;
  value?: RawValueType;
  disabled: boolean;
  onClose: (event?: MouseEvent) => void;
  closable: boolean;
  isMaxTag: boolean;
  index?: number;
}

export type OptionRenderFn = (
  option: FlattenOptionData<DefaultOptionType>,
  info: { index: number },
) => VNodeChild;

export type LabelRenderFn = (props: LabelInValueType) => VNodeChild;

export type TagRenderFn = (props: CustomTagProps) => VNodeChild;

export type PopupRenderFn = (menu: unknown) => VNodeChild;

export type ScrollToArg =
  | number
  | {
      index?: number;
      align?: 'top' | 'bottom' | 'auto';
      key?: string | number;
    };

// ---------------------------------------------------------------------------
// 实例句柄（antd `RefSelectProps` = rc `BaseSelectRef`）
// ---------------------------------------------------------------------------

export interface SelectRef {
  focus: (options?: FocusOptions) => void;
  blur: () => void;
  scrollTo: (arg?: ScrollToArg) => void;
  nativeElement: HTMLElement | null;
}

// ---------------------------------------------------------------------------
// Props
// ---------------------------------------------------------------------------

export interface SelectProps<ValueType = SelectValue> {
  // ---- 身份 ----
  id?: string;
  prefixCls?: string;
  /** ⚠️ Vue 原生 `class` / `style` 走 attrs（不是 prop）；这里只为类型面留位。 */
  class?: unknown;

  // ---- 值 ----
  value?: ValueType;
  defaultValue?: ValueType;
  /** 输出 `{ label, value }` 而非裸值。 */
  labelInValue?: boolean;
  /** 回填值取 option 的哪个字段（默认 `label`）。 */
  optionLabelProp?: string;
  fieldNames?: FieldNames;

  // ---- 模式 ----
  mode?: SelectMode;

  // ---- 选项 ----
  options?: DefaultOptionType[];
  /** 搜索时列表的最大高度（默认 256）。 */
  listHeight?: number;
  /** 虚拟滚动的估算行高（默认 controlHeight = 32）。 */
  listItemHeight?: number;
  virtual?: boolean;
  /** 键盘上下键是否自动激活第一项（默认 true，combobox 为 false）。 */
  defaultActiveFirstOption?: boolean;
  // ---- 搜索 ----
  showSearch?: boolean | SelectSearchConfig;
  /** Search text; supports v-model:searchValue. */
  searchValue?: string;
  /** @deprecated 用 `showSearch.autoClearSearchValue` */
  autoClearSearchValue?: boolean;
  /** @deprecated 用 `showSearch.filterOption` */
  filterOption?: boolean | FilterFunc<DefaultOptionType>;
  /** @deprecated 用 `showSearch.filterSort` */
  filterSort?: SearchConfig<DefaultOptionType>['filterSort'];
  /** @deprecated 用 `showSearch.optionFilterProp` */
  optionFilterProp?: string | string[];

  // ---- 外观 ----
  size?: SelectSize;
  variant?: SelectVariant;
  /** @deprecated 用 `variant` */
  bordered?: boolean;
  status?: SelectStatus;
  disabled?: boolean;
  loading?: boolean;
  placeholder?: string;
  /** @deprecated 默认显示箭头，隐藏请用空的 `#suffixIcon` 插槽或 `showArrow: false` */
  showArrow?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild; label?: string };
  maxLength?: number;

  // ---- 多选 ----
  maxCount?: number;
  maxTagCount?: number;
  maxTagTextLength?: number;
  tokenSeparators?: string[] | ((input: string) => string[]);

  // ---- 浮层 ----
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  direction?: SelectDirection;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement | ShadowRoot;
  transitionName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  popupClassName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  dropdownClassName?: string;
  /** @deprecated 用 `styles.popup.root` */
  dropdownStyle?: CSSProperties;
  popupStyle?: CSSProperties;

  // ---- 语义槽 ----
  classNames?: SelectSemanticClassNames;
  styles?: SelectSemanticStyles;

  // ---- 无障碍 ----
  tabIndex?: number;
  autoFocus?: boolean;
  title?: string;
  role?: string;
}

// ---------------------------------------------------------------------------
// 事件（Vue 侧：语义事件 + v-model 同发，见 PITFALLS 162）
// ---------------------------------------------------------------------------

export interface SelectEmits<ValueType = SelectValue> {
  change: [value: ValueType, option: DefaultOptionType | DefaultOptionType[] | undefined];
  'update:value': [value: ValueType];
  select: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  deselect: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  search: [value: string];
  'update:searchValue': [value: string];
  openChange: [open: boolean];
  'update:open': [open: boolean];
  focus: [event: FocusEvent];
  blur: [event: FocusEvent];
  clear: [];
  popupScroll: [event: Event];
  inputKeyDown: [event: KeyboardEvent];
}

// ---------------------------------------------------------------------------
// Slots（规则 C8-R2：ReactNode / render prop 一律 slot —— **不**保留同名 prop。
// 文本类 prop（placeholder）保留 string 便捷形态，slot 优先。）
// ---------------------------------------------------------------------------

export interface SelectSlots {
  default?: () => VNodeChild;
  prefix?: () => VNodeChild;
  suffixIcon?: (props: {
    searchValue: string;
    open: boolean;
    focused: boolean;
    showSearch: boolean;
    loading?: boolean;
  }) => VNodeChild;
  searchIcon?: () => VNodeChild;
  loadingIcon?: () => VNodeChild;
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  menuItemSelectedIcon?: (props: {
    value?: unknown;
    disabled?: boolean;
    isSelected?: boolean;
  }) => VNodeChild;
  placeholder?: () => VNodeChild;
  notFoundContent?: () => VNodeChild;
  optionRender?: (props: {
    option: FlattenOptionData<DefaultOptionType>;
    index: number;
  }) => VNodeChild;
  tagRender?: (props: CustomTagProps) => VNodeChild;
  labelRender?: (props: LabelInValueType) => VNodeChild;
  popupRender?: (props: { menu: VNodeChild }) => VNodeChild;
  maxTagPlaceholder?: (props: { omittedValues: DisplayValueType[] }) => VNodeChild;
}
```

### ../hooks/search.ts

```ts
/**
 * Cascader 的搜索 hooks —— `useSearchConfig` / `useSearchOptions` 的 Vue 版。
 *
 * 判据（docs/analysis/cascader.md §3.4）：
 * - `showSearch` 为对象时合入默认配置（`matchInputWidth: true` / `limit: 50`）；
 * - `limit <= 0` 视为 false（不限制）；
 * - 过滤只在**叶子**（或 changeOnSelect / 多选的任意层）上做；命中的结果项用
 *   `render` 产出 label（antd 薄壳会注入带高亮的 render），并挂 `SEARCH_MARK`
 *   保存完整路径（展示与回填都需要它）；
 * - `sort` 提供时覆盖默认顺序。
 */

import { type ComputedRef, computed, type Ref } from 'vue';

import {
  type BaseOptionType,
  type FieldNames,
  type FilledFieldNames,
  fillFieldNames,
  getOptionChildren,
  getOptionLabel,
  getOptionValue,
  getSearchPath,
  SEARCH_MARK,
} from '../utils';

export interface SearchConfig {
  filter?: (
    searchValue: string,
    pathOptions: BaseOptionType[],
    fieldNames: { label: string },
  ) => boolean;
  render?: (
    inputValue: string,
    pathOptions: BaseOptionType[],
    prefixCls: string,
    fieldNames: FieldNames,
  ) => unknown;
  sort?: (
    a: BaseOptionType[],
    b: BaseOptionType[],
    searchValue: string,
    fieldNames: FieldNames,
  ) => number;
  matchInputWidth?: boolean;
  limit?: number | false;
  autoClearSearchValue?: boolean;
}

/** `showSearch` → [是否开启, 配置]（上游 useSearchConfig）。 */
export function normalizeSearchConfig(
  showSearch: boolean | Omit<SearchConfig, 'render'> | undefined,
  props: { autoClearSearchValue?: boolean },
): [boolean, SearchConfig] {
  if (!showSearch) return [false, {}];

  let searchConfig: SearchConfig = {
    matchInputWidth: true,
    limit: 50,
    autoClearSearchValue: props.autoClearSearchValue,
  };
  if (showSearch && typeof showSearch === 'object') {
    const {
      filter,
      sort,
      matchInputWidth = true,
      limit = 50,
      autoClearSearchValue = props.autoClearSearchValue,
    } = showSearch;
    searchConfig = { filter, sort, matchInputWidth, limit, autoClearSearchValue };
  }
  if (typeof searchConfig.limit === 'number' && searchConfig.limit <= 0) {
    searchConfig.limit = false;
  }
  return [true, searchConfig];
}

const defaultFilter = (
  search: string,
  options: BaseOptionType[],
  { label = '' }: { label?: string },
): boolean =>
  options.some((opt) =>
    String(opt[label] ?? '')
      .toLowerCase()
      .includes(search.toLowerCase()),
  );

const defaultRender = (
  _inputValue: string,
  path: BaseOptionType[],
  _prefixCls: string,
  fieldNames: FieldNames,
): unknown => {
  const fields = fillFieldNames(fieldNames);
  const labels = path.map((option) =>
    getOptionLabel(option, fields, getOptionValue(option, fields)),
  );
  return labels.every((label) => typeof label === 'string' || typeof label === 'number')
    ? labels.join(' / ')
    : labels.flatMap((label, index) => (index ? [' / ', label] : [label]));
};

/** 搜索态的候选 options（过滤 + render + limit + sort；上游 useSearchOptions）。 */
export function computeSearchOptions(
  search: string,
  options: BaseOptionType[],
  fieldNames: FilledFieldNames,
  prefixCls: string,
  config: SearchConfig,
  enableHalfPath: boolean,
): BaseOptionType[] {
  const { filter = defaultFilter, render = defaultRender, limit = 50, sort } = config;

  const filteredOptions: BaseOptionType[] = [];
  if (!search) return [];

  function dig(
    list: BaseOptionType[],
    pathOptions: BaseOptionType[],
    parentDisabled = false,
  ): void {
    list.forEach((option) => {
      // 无 sort 且有 limit 时攒够即停（上游的 perf saving）
      if (!sort && limit !== false && limit > 0 && filteredOptions.length >= limit) return;

      const connectedPathOptions = [...pathOptions, option];
      const children = getOptionChildren(option, fieldNames);
      const mergedDisabled = parentDisabled || !!option.disabled;

      // 只在叶子（或 changeOnSelect / 多选的任意层）上做过滤
      if (!children || children.length === 0 || enableHalfPath) {
        if (filter(search, connectedPathOptions, { label: fieldNames.label })) {
          filteredOptions.push({
            ...option,
            disabled: mergedDisabled,
            [fieldNames.label]: render(search, connectedPathOptions, prefixCls, {
              label: fieldNames.label,
              value: fieldNames.value,
              children: fieldNames.children,
            }),
            [SEARCH_MARK]: connectedPathOptions,
            [fieldNames.children]: undefined,
          });
        }
      }
      if (children) {
        dig(children, connectedPathOptions, mergedDisabled);
      }
    });
  }
  dig(options, []);

  if (sort) {
    filteredOptions.sort((a, b) =>
      sort(getSearchPath(a) ?? [], getSearchPath(b) ?? [], search, {
        label: fieldNames.label,
        value: fieldNames.value,
        children: fieldNames.children,
      }),
    );
  }
  return limit !== false && limit > 0 ? filteredOptions.slice(0, limit) : filteredOptions;
}

/** 响应式包装（供组件层使用）。 */
export function useSearchOptions(
  search: Ref<string>,
  options: ComputedRef<BaseOptionType[]>,
  fieldNames: Ref<FilledFieldNames>,
  prefixCls: Ref<string>,
  config: Ref<SearchConfig>,
  enableHalfPath: boolean,
): ComputedRef<BaseOptionType[]> {
  return computed(() =>
    computeSearchOptions(
      search.value,
      options.value,
      fieldNames.value,
      prefixCls.value,
      config.value,
      enableHalfPath,
    ),
  );
}
```

### ../utils.ts

```ts
import { isVNode, type VNodeChild } from 'vue';
import { convertDataToEntities, type DataEntity } from './engine/tree';

/** Internal path keys retain both the value type and path boundaries. */
export const SHOW_PARENT = 'SHOW_PARENT';
export const SHOW_CHILD = 'SHOW_CHILD';
export type ShowCheckedStrategy = typeof SHOW_PARENT | typeof SHOW_CHILD;
export interface FieldNames {
  label?: string;
  value?: string;
  children?: string;
}
export interface FilledFieldNames {
  label: string;
  value: string;
  key: string;
  children: string;
}
export type BaseOptionType = Record<string, unknown> & {
  disabled?: boolean;
  isLeaf?: boolean;
  loading?: boolean;
};
export type DefaultOptionType = BaseOptionType & {
  label?: VNodeChild;
  value?: string | number;
  children?: DefaultOptionType[];
};
export type ValueCell = (string | number)[];
export type RawValue = string | number | ValueCell;

export function toPathKey(value: ValueCell): string {
  return JSON.stringify(value);
}
export function toPathKeys(values: ValueCell[]): string[] {
  return values.map(toPathKey);
}
export function toPathValueStr(pathKey: string): string[] {
  const value: unknown = JSON.parse(pathKey);
  if (!Array.isArray(value) || !value.every(isValue))
    throw new TypeError('[Cascader] Invalid path key');
  return value.map(String);
}
export function fillFieldNames(fieldNames?: FieldNames): FilledFieldNames {
  const { label = 'label', value = 'value', children = 'children' } = fieldNames ?? {};
  return { label, value, key: value, children };
}
export function isValue(value: unknown): value is string | number {
  return typeof value === 'string' || typeof value === 'number';
}
export function getOptionValue(option: BaseOptionType, fields: FilledFieldNames): string | number {
  const value = option[fields.value];
  if (!isValue(value))
    throw new TypeError(`[Cascader] Option ${fields.value} must be a string or number`);
  return value;
}
export function isOption(value: unknown): value is BaseOptionType {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}
export function getOptionChildren(
  option: BaseOptionType | undefined,
  fields: FilledFieldNames,
): BaseOptionType[] {
  const children = option?.[fields.children];
  if (children === undefined || children === null) return [];
  if (!Array.isArray(children) || !children.every(isOption))
    throw new TypeError(`[Cascader] Option ${fields.children} must be an array of options`);
  return children;
}
export function getSearchPath(option: BaseOptionType): BaseOptionType[] | undefined {
  const path = option[SEARCH_MARK];
  return Array.isArray(path) && path.every(isOption) ? path : undefined;
}
export function toContent(value: unknown): VNodeChild {
  if (
    value === undefined ||
    value === null ||
    typeof value === 'string' ||
    typeof value === 'number' ||
    typeof value === 'boolean' ||
    isVNode(value)
  )
    return value;
  if (Array.isArray(value)) return value.map(toContent);
  throw new TypeError('[Cascader] Option labels must be Vue renderable content');
}
export function getOptionLabel(
  option: BaseOptionType | null,
  fields: FilledFieldNames,
  fallback: string | number,
): VNodeChild {
  const label = option?.[fields.label];
  return label === undefined ? fallback : toContent(label);
}
export function isLeaf(option: BaseOptionType | undefined, fields: FilledFieldNames): boolean {
  return option?.isLeaf ?? getOptionChildren(option, fields).length === 0;
}
export function scrollIntoParentView(element: HTMLElement): void {
  const parent = element.parentElement;
  if (!parent) return;
  const offset = element.offsetTop - parent.offsetTop;
  if (offset < parent.scrollTop) parent.scrollTo({ top: offset });
  else if (offset + element.clientHeight > parent.scrollTop + parent.clientHeight)
    parent.scrollTo({ top: offset + element.clientHeight - parent.clientHeight });
}
export const SEARCH_MARK = '__rc_cascader_search_mark__';
export function getFullPathKeys(
  options: BaseOptionType[],
  fields: FilledFieldNames,
): (ValueCell | undefined)[] {
  return options.map((option) =>
    getSearchPath(option)?.map((node) => getOptionValue(node, fields)),
  );
}
function isValueCell(value: unknown): value is ValueCell {
  return Array.isArray(value) && value.every(isValue);
}
export function toRawValues(value: RawValue | RawValue[] | undefined): ValueCell[] {
  if (value === undefined) return [];
  if (isValue(value)) return [[value]];
  if (!value.length) return [];
  if (isValueCell(value)) return [value];
  return value.map((path) => {
    if (!isValueCell(path))
      throw new TypeError('[Cascader] Values must be paths of strings or numbers');
    return path;
  });
}
export function formatStrategyValues(
  pathKeys: string[],
  getEntities: () => Record<string, DataEntity>,
  strategy: ShowCheckedStrategy,
): string[] {
  const checked = new Set(pathKeys);
  const entities = getEntities();
  return pathKeys.filter((key) => {
    const entity = Object.hasOwn(entities, key) ? entities[key] : undefined;
    if (entity?.node.disabled) return true;
    return strategy === SHOW_CHILD
      ? !entity?.children?.some((child) => checked.has(child.key))
      : !(entity?.parent && !entity.parent.node.disabled && checked.has(entity.parent.key));
  });
}
export interface PathOption {
  value: string | number;
  index: number;
  option: BaseOptionType | null;
}
export function toPathOptions(
  path: ValueCell,
  options: BaseOptionType[],
  fields: FilledFieldNames,
  stringMode = false,
): PathOption[] {
  let list = options;
  return path.map((value) => {
    const index = list.findIndex((option) =>
      stringMode ? String(option[fields.value]) === String(value) : option[fields.value] === value,
    );
    const option = list[index] ?? null;
    list = getOptionChildren(option ?? undefined, fields);
    return { value: option ? getOptionValue(option, fields) : value, index, option };
  });
}
export { convertDataToEntities };
```

### ../engine/tree.ts

```ts
/**
 * Cascader 依赖的两棵「树算法」—— `@rc-component/tree` 的 Vue 版移植。
 *
 * ── 为什么在这里，而不是独立包 ──────────────────────────────────────────────
 *
 * `foundation.json` 的开放决策 `early-extract-table-core-tree-core` 结论是
 * **A：不提前抽取独立包，等第二个消费者出现**。Cascader（多选的勾选传导）是第一个
 * 消费者，所以算法先落在 `cascader/engine/`；将来 Tree 组件需要时再按
 * `ActionButton` 那套做法提升到 `_internal/`（原位置留垫片）。
 *
 * ── 两个算法 ────────────────────────────────────────────────────────────────
 *
 * 1. `convertDataToEntities(dataNodes, config)` —— 把嵌套 options 摊成扁平实体表，
 *    并补出 `parent` / `children`（实体层面）与 `level` / `pos` / `nodes`（路径）。
 * 2. `conductCheck(keyList, checked, keyEntities)` —— 勾选传导：
 *    - `checked === true`（fill）：父选中 ⇒ 向下补全所有子；子全选 ⇒ 向上补父；
 *      部分选中 ⇒ 父记 halfChecked。
 *    - `checked === { checked: false, halfCheckedKeys }`（clean）：反向清理。
 *
 * 契约来源：`@rc-component/tree@1.x` 的 `es/utils/treeUtil.js`（convertDataToEntities /
 * traverseDataNodes）与 `es/utils/conductUtil.js`（conductCheck / fill+clean）。
 * 行为逐条对齐，**不复制源码**。
 */

/** 树节点实体。 */
export interface DataEntity {
  /** 原始节点。 */
  node: Record<string, unknown>;
  /** 从根到当前节点的原始节点链（Cascader 用它拼 pathKey）。 */
  nodes: Record<string, unknown>[];
  /** 在同级中的下标。 */
  index: number;
  /** 节点 key（`getKey(key, pos)`：key 缺失时回退 pos）。 */
  key: string;
  /** 位置串（形如 `0-1-2`）。 */
  pos: string;
  /** 层级（根为 0）。 */
  level: number;
  /** 父实体（根为 undefined）。 */
  parent?: DataEntity;
  /** 子实体列表（构造期填充）。 */
  children?: DataEntity[];
}

export interface Wrapper {
  posEntities: Record<string, DataEntity>;
  keyEntities: Record<string, DataEntity>;
  [key: string]: unknown;
}

export interface ConvertConfig {
  /** 用自定义字段解析（Cascader 传 `{ key: value字段, children }`）。 */
  fieldNames?: { key?: string; children?: string };
  /** 包装器扩展（Cascader 用它挂 `pathKeyEntities`）。 */
  initWrapper?: (wrapper: Wrapper) => Wrapper | undefined;
  /** 每个实体构造后的钩子（Cascader 用它把 key 覆写成 pathKey）。 */
  processEntity?: (entity: DataEntity, wrapper: Wrapper) => void;
  /** 全部处理完的钩子。 */
  onProcessFinished?: (wrapper: Wrapper) => void;
}

const DEFAULT_FIELD_NAMES = { key: 'key', children: 'children' };

function getPosition(level: string | number, index: number): string {
  return `${level}-${index}`;
}

function getKey(key: unknown, pos: string): string {
  return key !== null && key !== undefined ? String(key) : pos;
}

/**
 * 遍历嵌套数据（广度优先按层级展开，与上游同序）。
 *
 * ⚠️ 上游 `traverseDataNodes` 的 `nodes` 是**路径链**（根→当前），不是 children ——
 *    Cascader 的 typed value path 依赖完整的 nodes 路径。
 */
export function traverseDataNodes(
  dataNodes: Record<string, unknown>[],
  callback: (item: {
    node: Record<string, unknown>;
    index: number;
    pos: string;
    key: string;
    parentPos: string;
    level: number;
    nodes: Record<string, unknown>[];
  }) => void,
  config: ConvertConfig = {},
): void {
  const { key: fieldKey, children: fieldChildren } = {
    ...DEFAULT_FIELD_NAMES,
    ...(config.fieldNames ?? {}),
  };

  /**
   * @param level 本节点的 level；根调用传 **0** ⇒ 第一层节点的 level 为 0
   *              （rc-tree 的 level 从 0 起算）。⚠️ 不能用 `parentLevel + 1`
   *              的写法——虚拟根会把 -1 加成 0 再传给子，整体偏移一层。
   */
  function processNode(
    node: Record<string, unknown> | null,
    index: number,
    parent: { pos: string; level: number } | null,
    pathNodes: Record<string, unknown>[],
    level: number,
  ): void {
    const mergedParent = parent as { pos: string; level: number } | undefined;
    const children = (node ? node[fieldChildren] : dataNodes) as
      | Record<string, unknown>[]
      | undefined;
    // biome-ignore lint/style/noNonNullAssertion: node 非空时 mergedParent 必由调用方给出（pos/parentPos 都从它派生）
    const pos = node ? getPosition(mergedParent!.pos, index) : '0';
    const connectNodes = node ? [...pathNodes, node] : [];

    if (node) {
      callback({
        node,
        index,
        pos,
        key: getKey(node[fieldKey], pos),
        // biome-ignore lint/style/noNonNullAssertion: 同上 —— 这一支只在 node 非空时执行
        parentPos: mergedParent!.pos,
        level,
        nodes: connectNodes,
      });
    }

    (children ?? []).forEach((child, childIndex) => {
      processNode(child, childIndex, { pos, level }, connectNodes, level + 1);
    });
  }

  // ⚠️ 虚拟根的 level 是 **-1**：递归里 `level + 1` 后第一层节点的 level 才是 0
  //    （rc-tree 的 level 从 0 起算；传 0 会让整棵树偏移一层，conduct 的层级分组全错）
  processNode(null, 0, { pos: '0', level: -1 }, [], -1);
}

/**
 * 摊平嵌套数据为实体表。
 *
 * 与上游同构：同时产出 `posEntities` 与 `keyEntities`，`initWrapper` 可扩展包装器，
 * `processEntity` 在每个实体建好后回调（Cascader 借此把 `entity.key` 覆写成 pathKey）。
 */
export function convertDataToEntities(
  dataNodes: Record<string, unknown>[],
  config: ConvertConfig = {},
): Wrapper {
  const posEntities: Record<string, DataEntity> = {};
  const keyEntities: Record<string, DataEntity> = {};
  let wrapper: Wrapper = { posEntities, keyEntities };
  if (config.initWrapper) {
    wrapper = config.initWrapper(wrapper) ?? wrapper;
  }

  traverseDataNodes(
    dataNodes,
    (item) => {
      const { node, index, pos, key, parentPos, level, nodes } = item;
      const entity: DataEntity = { node, nodes, index, key, pos, level };
      const mergedKey = getKey(key, pos);

      Object.defineProperty(posEntities, pos, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });
      Object.defineProperty(keyEntities, mergedKey, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });

      entity.parent = Object.hasOwn(posEntities, parentPos) ? posEntities[parentPos] : undefined;
      if (entity.parent) {
        entity.parent.children = entity.parent.children || [];
        entity.parent.children.push(entity);
      }

      config.processEntity?.(entity, wrapper);
    },
    config,
  );

  config.onProcessFinished?.(wrapper);
  return wrapper;
}

// ================================ conduct ================================

export interface ConductResult {
  checkedKeys: string[];
  halfCheckedKeys: string[];
}

/** 上游 `isCheckDisabled`：`disabled` / `disableCheckbox` / `checkable === false`。 */
function isCheckDisabled(node: Record<string, unknown> | undefined): boolean {
  if (!node) return false;
  const { disabled, disableCheckbox, checkable } = node as {
    disabled?: boolean;
    disableCheckbox?: boolean;
    checkable?: boolean;
  };
  return !!(disabled || disableCheckbox) || checkable === false;
}

function removeFromCheckedKeys(
  halfCheckedKeys: Set<string>,
  checkedKeys: Set<string>,
): Set<string> {
  const filtered = new Set<string>();
  halfCheckedKeys.forEach((key) => {
    if (!checkedKeys.has(key)) filtered.add(key);
  });
  return filtered;
}

/** 按层级分组（上游 `conductCheck` 的第一步）。 */
function groupByLevel(keyEntities: Record<string, DataEntity>) {
  const levelEntities = new Map<number, Set<DataEntity>>();
  let maxLevel = 0;
  Object.keys(keyEntities).forEach((key) => {
    // noUncheckedIndexedAccess：索引访问可能 undefined（key 来自 Object.keys，防御式收窄）
    const entity = Object.hasOwn(keyEntities, key) ? keyEntities[key] : undefined;
    if (!entity) return;
    const { level } = entity;
    // ⚠️ 用局部变量接住（`get(...)!` 消不掉，且 `Map.get` 的返回类型永远是 `T | undefined`）
    let levelSet = levelEntities.get(level);
    if (!levelSet) {
      levelSet = new Set();
      levelEntities.set(level, levelSet);
    }
    levelSet.add(entity);
    maxLevel = Math.max(maxLevel, level);
  });
  return { levelEntities, maxLevel };
}

/** 自底向上：父的全部（非禁用）子是否都选中 / 部分选中。 */
function conductParent(
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  checkedKeys: Set<string>,
  halfCheckedKeys: Set<string>,
  getDisabled: (node: Record<string, unknown>) => boolean,
  onAllChecked: (parentKey: string) => void,
  onPartialChecked: (parentKey: string) => void,
): void {
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { node } = entity;
      const parent = entity.parent;
      if (!parent || getDisabled(node) || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const checked = checkedKeys.has(key);
          if (allChecked && !checked) allChecked = false;
          if (!partialChecked && (checked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (allChecked) onAllChecked(parent.key);
      if (partialChecked) onPartialChecked(parent.key);
      visitedKeys.add(parent.key);
    });
  }
}

function fillConductCheck(
  keys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  const halfCheckedKeys = new Set<string>();

  // 自顶向下：父选中 ⇒ 补子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (checkedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.add(childEntity.key);
          });
      }
    });
  }

  // 自底向上：子全选 ⇒ 补父；部分 ⇒ half
  conductParent(
    levelEntities,
    maxLevel,
    checkedKeys,
    halfCheckedKeys,
    getDisabled,
    (parentKey) => checkedKeys.add(parentKey),
    (parentKey) => halfCheckedKeys.add(parentKey),
  );

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

function cleanConductCheck(
  keys: Set<string>,
  halfKeys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  let halfCheckedKeys = new Set(halfKeys);

  // 自顶向下：未选中且非半选 ⇒ 清掉子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (!checkedKeys.has(key) && !halfCheckedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.delete(childEntity.key);
          });
      }
    });
  }

  // ⚠️ 自底向上必须**单遍**：`delete(parent.key)` 会立刻影响更高一层的判定
  //    （上游就是同一轮里先算 allChecked / partialChecked 再改 checkedKeys）。
  //    拆成两遍会让高层读到「本该删掉的父」，half 集合偏大。
  halfCheckedKeys = new Set<string>();
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { parent, node } = entity;
      if (getDisabled(node) || !parent || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const isChecked = checkedKeys.has(key);
          if (allChecked && !isChecked) allChecked = false;
          if (!partialChecked && (isChecked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (!allChecked) checkedKeys.delete(parent.key);
      if (partialChecked) halfCheckedKeys.add(parent.key);
      visitedKeys.add(parent.key);
    });
  }

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

/**
 * 勾选传导。
 *
 * @param keyList 当前 key 列表
 * @param checked `true` = fill（补全）；`{ checked: false, halfCheckedKeys }` = clean（清理）
 * @param keyEntities `convertDataToEntities` 产出的 `keyEntities`
 */
export function conductCheck(
  keyList: string[],
  checked: true | { checked: false; halfCheckedKeys: string[] },
  keyEntities: Record<string, DataEntity>,
  getCheckDisabled?: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const getDisabled = getCheckDisabled ?? isCheckDisabled;

  // 只处理存在的 key（上游会 warning 缺失的 key，本仓静默过滤）
  const keys = new Set(keyList.filter((key) => Object.hasOwn(keyEntities, key)));

  const { levelEntities, maxLevel } = groupByLevel(keyEntities);

  if (checked === true) {
    return fillConductCheck(keys, levelEntities, maxLevel, getDisabled);
  }
  return cleanConductCheck(
    keys,
    new Set(checked.halfCheckedKeys),
    levelEntities,
    maxLevel,
    getDisabled,
  );
}
```

## 勾选策略 (show-checked-strategy)

多选时 `showCheckedStrategy` 决定回填值：`SHOW_PARENT` 向上收成父级路径，`SHOW_CHILD` 保留实际勾选的叶子路径；两组的回填文案会随选择同步变化。

### show-checked-strategy.vue

```vue
<script setup lang="ts">
// 对齐 antd 的多选勾选策略：SHOW_PARENT / SHOW_CHILD
import { CASCADER_SHOW_CHILD, CASCADER_SHOW_PARENT, Cascader, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';
import type { CascaderOutputValue } from '../interface';

const parentValue = ref<CascaderOutputValue>([['zhejiang', 'hangzhou']]);
const childValue = ref<CascaderOutputValue>([['zhejiang', 'hangzhou']]);

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      { value: 'nanjing', label: '南京' },
      { value: 'suzhou', label: '苏州' },
    ],
  },
];

const parentDisplay = computed(() =>
  parentValue.value.length
    ? parentValue.value
        .map((path) => (Array.isArray(path) ? path.join(' / ') : String(path)))
        .join('；')
    : '尚未选择',
);
const childDisplay = computed(() =>
  childValue.value.length
    ? childValue.value
        .map((path) => (Array.isArray(path) ? path.join(' / ') : String(path)))
        .join('；')
    : '尚未选择',
);
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px">
    <div>
      <Tag color="blue">SHOW_PARENT</Tag>
      <Cascader
        v-model:value="parentValue"
        multiple
        :show-checked-strategy="CASCADER_SHOW_PARENT"
        :options="options"
        placeholder="选中子级后回填父级路径"
        style="margin-top: 8px"
      />
      <p style="margin-bottom: 0">回填值：{{ parentDisplay }}</p>
    </div>

    <div>
      <Tag color="green">SHOW_CHILD</Tag>
      <Cascader
        v-model:value="childValue"
        multiple
        :show-checked-strategy="CASCADER_SHOW_CHILD"
        :options="options"
        placeholder="选中子级后保留叶子路径"
        style="margin-top: 8px"
      />
      <p style="margin-bottom: 0">回填值：{{ childDisplay }}</p>
    </div>
  </div>
</template>
```

### ../interface.ts

```ts
import type { CSSProperties, VNode, VNodeChild } from 'vue';
import type { SemanticInput } from '../_internal/use-merge-semantic';
import type { SizeType } from '../config-provider/size-context';
import type { SelectCommonPlacement, SelectSlots, SelectVariant } from '../select/interface';
import type { SearchConfig } from './hooks/search';
import type { BaseOptionType, FieldNames, RawValue, ShowCheckedStrategy, ValueCell } from './utils';

export type CascaderValue = RawValue | ValueCell[];
export type CascaderOutputValue = ValueCell | ValueCell[];
export type CascaderSelectedOptions = (BaseOptionType | null)[] | (BaseOptionType | null)[][];
export type CascaderSearchConfig = Omit<SearchConfig, 'render' | 'searchValue' | 'onSearch'>;
export interface CascaderSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: { root?: string; list?: string; listItem?: string };
}
export interface CascaderSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: { root?: CSSProperties; list?: CSSProperties; listItem?: CSSProperties };
}
export interface CascaderPanelProps {
  prefixCls?: string;
  options?: BaseOptionType[];
  value?: CascaderValue;
  defaultValue?: CascaderValue;
  multiple?: boolean;
  fieldNames?: FieldNames;
  changeOnSelect?: boolean;
  showCheckedStrategy?: ShowCheckedStrategy;
  loadData?: (selectedOptions: BaseOptionType[]) => void | Promise<void>;
  expandTrigger?: 'click' | 'hover';
  expandIcon?: VNodeChild;
  loadingIcon?: VNodeChild;
  direction?: 'ltr' | 'rtl';
  notFoundContent?: VNodeChild;
  disabled?: boolean;
  popupMenuColumnStyle?: CSSProperties;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderPanelProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderPanelProps>;
  'onUpdate:value'?: (value: CascaderOutputValue) => void;
  onChange?: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
}
export interface CascaderProps extends Omit<CascaderPanelProps, 'classNames' | 'styles'> {
  id?: string;
  checkable?: boolean;
  size?: SizeType;
  loading?: boolean;
  variant?: SelectVariant;
  bordered?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild };
  clearIcon?: VNodeChild;
  removeIcon?: VNodeChild;
  suffixIcon?: VNodeChild;
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  showSearch?: boolean | CascaderSearchConfig;
  searchValue?: string;
  autoClearSearchValue?: boolean;
  placeholder?: VNodeChild;
  popupClassName?: string;
  dropdownClassName?: string;
  popupStyle?: CSSProperties;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement;
  status?: 'error' | 'warning';
  maxTagCount?: number;
  maxTagTextLength?: number;
  maxTagPlaceholder?: VNodeChild;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderProps>;
  'onUpdate:open'?: (open: boolean) => void;
  'onUpdate:searchValue'?: (value: string) => void;
  onOpenChange?: (open: boolean) => void;
  onSearch?: (value: string) => void;
  onFocus?: (event: FocusEvent) => void;
  onBlur?: (event: FocusEvent) => void;
  onClear?: () => void;
  onPopupScroll?: (event: Event) => void;
  onKeydown?: (event: KeyboardEvent) => void;
  onKeyup?: (event: KeyboardEvent) => void;
  onMousedown?: (event: MouseEvent) => void;
}
export interface CascaderEmits {
  'update:value': (value: CascaderOutputValue) => void;
  change: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
  'update:open': (open: boolean) => void;
  openChange: (open: boolean) => void;
  'update:searchValue': (value: string) => void;
  search: (value: string) => void;
  focus: (event: FocusEvent) => void;
  blur: (event: FocusEvent) => void;
  clear: () => void;
  popupScroll: (event: Event) => void;
  keydown: (event: KeyboardEvent) => void;
  keyup: (event: KeyboardEvent) => void;
  mousedown: (event: MouseEvent) => void;
}
export interface CascaderOptionSlots {
  optionRender?: (scope: { option: BaseOptionType; pathOptions: BaseOptionType[] }) => VNodeChild;
  searchRender?: (scope: {
    inputValue: string;
    pathOptions: BaseOptionType[];
    fieldNames: FieldNames;
  }) => VNodeChild;
  expandIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
  loadingIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
}
export interface CascaderPanelSlots extends CascaderOptionSlots {
  notFoundContent?: () => VNodeChild;
}
export interface CascaderSlots extends CascaderPanelSlots {
  default?: () => VNodeChild;
  placeholder?: () => VNodeChild;
  displayRender?: (scope: {
    labels: VNodeChild[];
    selectedOptions: (BaseOptionType | null)[];
  }) => VNodeChild;
  suffixIcon?: SelectSlots['suffixIcon'];
  searchIcon?: SelectSlots['suffixIcon'];
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  maxTagPlaceholder?: (scope: {
    omittedValues: { value: ValueCell; label: VNodeChild; disabled?: boolean }[];
  }) => VNodeChild;
  popupRender?: (scope: { menu: VNode }) => VNodeChild;
}
export interface CascaderRef {
  readonly nativeElement: HTMLElement | null;
  focus: (options?: FocusOptions) => void;
  blur: () => void;
}
```

### ../../_internal/use-merge-semantic.ts

````ts
/**
 * 语义化 `classNames` / `styles` 的合并。
 *
 * 契约来源：antd 6.6.4 的 `es/_util/hooks/useMergeSemantic/index.js`（**逐条对齐**）。
 *
 * 为什么单独抽出来：72 个组件里有 60 多个都有 `classNames` / `styles`，合并语义
 * 一旦不一致，就会出现「Button 的覆盖优先级和 Empty 不一样」这类只有用户才会发现的问题。
 * 所以合并规则集中在这里，组件只声明「合并哪些来源、按什么顺序」。
 *
 * ── 与 antd 的对应关系（合并顺序是契约，不能改）────────────────────────────────
 *
 * ```
 * // antd（Empty）
 * const [mergedClassNames, mergedStyles] = useMergeSemantic(
 *   [contextClassNames, classNames],                          // classNamesList
 *   [contextStyles, contextStyleRoot, styles, styleRoot],     // stylesList
 *   { props },
 * );
 * ```
 *
 * 其中 `contextStyleRoot = useSemanticRootStyle(contextStyle)`、`styleRoot = useSemanticRootStyle(style)`，
 * 即把 `style` 这个平铺的 prop 包成 `{ root: style }` 再进合并。
 *
 * 三条必须逐字保留的判据：
 *   1. **classNames 是「拼接」不是「覆盖」** —— `clsx(acc[key], curVal)`，同名键会连起来。
 *   2. **styles 是「逐键浅合并、后者胜」** —— 与 classNames 不同，这里不是拼接。
 *   3. **`style` prop 排在 `styles.root` 之后** —— 所以 `style` 会**覆盖** `styles.root`。
 *      这条最反直觉，也最容易被「顺手改成更合理的顺序」。
 *
 * ── 函数式变体（裁决 `empty-semantic-fn` = B：支持）───────────────────────────
 *
 * antd 允许传 `(info: { props }) => 对象`。我们在 `resolveSemantic` 里逐字对应：
 * 判据是 `isFunction(value) ? value(info) : value`，**没有**额外的「只在需要时求值」优化
 * —— 那种优化会让函数式与对象式的行为出现差异。
 *
 * ── `schema`（嵌套语义槽）—— **2026-10-03 补齐** ──────────────────────────────
 *
 * antd 的第四参 `schema` 用 `_default` 把「字符串形态的嵌套键」落到指定子槽
 * （`classNames.popup = 'x'` ≡ `classNames.popup = { root: 'x' }`），并在最后用
 * `fillObjectBySchema` 保证嵌套键**恒为对象**。
 *
 * 本仓此前没有它，用「只要有一侧是对象就递归」绕过 —— 那在**字符串与对象混用**时
 * 会产垃圾键（`Object.keys('x')`）。antd 6.6.4 里 **9 个组件**传了 schema
 * （`select` / `cascader` / `color-picker` / `menu` / `tabs` / `image` / `splitter` /
 * `input.Search` / `table`），Table 是第一个**真的需要**它的（`body.cell` / `header.cell`）。
 *
 * ⚠️ **两条语义并存、不能合并**：不给 schema 时保持本仓既有行为（7 个消费者钉住它），
 *    给了 schema 才走 antd 的 `mergeClassNamesBySchema`。
 *    判据见 `__tests__/use-merge-semantic.test.ts` 的「反向哨兵」那一条。
 *
 * ── 这个模块没有证明什么 ──────────────────────────────────────────────────────
 *   - 没证明各组件的**合并顺序声明**是对的。本模块只保证「给定顺序，合并结果正确」；
 *     顺序本身由各组件的 compat 用例与 antd 对照（Empty 见 `__tests__/semantic.test.ts`）。
 *   - 没证明**所有该传 schema 的组件都传了**。schema 档 2026-10-03 实现，
 *     select / cascader / color-picker / tabs / image（×2）/ splitter 已补第四参；
 *     menu 无语义通道、`input.Search` 未实现（见 `docs/KNOWN-ISSUES.md` §2 留痕）。
 *
 *   ⚠️ 无 schema 的宽松路径（`mergeClassNames`）**仍在服务既有消费者**：它在
 *     「字符串 + 对象混用」时会产垃圾键（`Object.keys('x')`）。这条**曾**登记在
 *     `docs/KNOWN-ISSUES.md`，该文件的 §1 已于 2026-10-07 清零、登记项转入 §2 的
 *     「已修 / 已裁决」；但宽松路径本身**未改**（7 个既有消费者的用例钉住它）。
 *     若将来统一到 schema 档，需同步改这 7 处并重跑它们的 L4/L6。
 */

import { isFunction } from '@apollo-design/utils';
import {
  type ComputedRef,
  type CSSProperties,
  computed,
  type MaybeRefOrGetter,
  toValue,
} from 'vue';

/** 函数式语义化拿到的上下文。与 antd 的 `{ props }` 同构。 */
export interface SemanticInfo<P> {
  props: P;
}

/** 对象式或函数式的语义化输入。 */
export type SemanticInput<T, P> = T | ((info: SemanticInfo<P>) => T | undefined);

/** 任意可响应化的输入。普通值、ref、getter 都接受（与 `toValue` 同构）。 */
export type MaybeSource<T> = MaybeRefOrGetter<T>;

/**
 * ⚠️ **刻意不用** `_internal/clsx.ts` 那一份（2026-10-07 核对过）。
 *
 * 这里是**更窄**的语义：只保留字符串，数字 / 数组 / 对象一律丢弃。
 * 而共享层那份会展开数组与对象（`{a:true}` → `'a'`）。语义化 `classNames` 的槽位值
 * 本来就是字符串，宽版本在这里只会把「传错了形态」静默变成一个类名。
 * ⇒ 别为了「消重」把它换成共享版 —— 那份窄语义是有意的。
 */
function clsx(...values: unknown[]): string {
  return values.filter((v) => typeof v === 'string' && v !== '').join(' ');
}

/**
 * 求值一个语义化输入。
 *
 * 与 antd 的 `resolveStyleOrClass(value, info)` 逐字对应 —— 包括
 * **只在 `isFunction` 时求值**这一点：传 `null` / `undefined` 会原样返回，
 * 由下游的 `filter(Boolean)` 丢掉。
 */
export function resolveSemantic<T, P>(
  value: SemanticInput<T, P> | undefined | null,
  info: SemanticInfo<P>,
): T | undefined {
  if (value === undefined || value === null) return undefined;
  return isFunction(value) ? (value as (i: SemanticInfo<P>) => T | undefined)(info) : value;
}

/**
 * 合并 classNames。**拼接**语义：同名键连起来，不覆盖。
 *
 * 与 antd 的 `mergeClassNames(schema, ...classNames)` 在 `schema === undefined` 时等价。
 *
 * ⚠️ 实现里有一次类型断言（`as Record<string, string | undefined>`）。
 *    它**不是**类型漏洞，而是「语义键集合由调用方的泛型决定」这一事实的必然结果：
 *    函数体只做键的遍历与字符串拼接，不认识任何具体键。用 `as any` 才是漏洞，
 *    这里断言到的是精确的中间形态。
 */
export function mergeClassNames<CN extends object>(
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const cur = record[key];
      const prev = acc[key];
      // 嵌套语义对象（如 Select 的 classNames.popup.{root,list,listItem}）递归合并；
      // 叶子值按 clsx 拼接（select 期 AutoComplete 抓出：浅合并在 popup 上丢数据）
      if (isPlainRecord(cur) || isPlainRecord(prev)) {
        acc[key] = mergeClassNames((prev ?? {}) as never, (cur ?? {}) as never);
      } else {
        acc[key] = clsx(prev as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

function isPlainRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// ---------------------------------------------------------------------------
// schema（嵌套语义槽）—— antd `useMergeSemantic` 的第四参
// ---------------------------------------------------------------------------

/**
 * schema 的**键名首字符**集合。
 *
 * 与 antd 的 `ValidChar`（`_util/type.ts:91`）**逐字相同**：**只有小写 a–z**。
 * 这不是「随便写的」—— 它正是让 `_default`（下划线开头）**不落进**索引签名、
 * 从而不与 `{ _default?: string }` 冲突的机制。
 * ⇒ 别「顺手」把大写或下划线加进来（会让 `SemanticSchema` 立刻变成 `never` 交叉）。
 */
type LowerChar =
  | 'a'
  | 'b'
  | 'c'
  | 'd'
  | 'e'
  | 'f'
  | 'g'
  | 'h'
  | 'i'
  | 'j'
  | 'k'
  | 'l'
  | 'm'
  | 'n'
  | 'o'
  | 'p'
  | 'q'
  | 'r'
  | 's'
  | 't'
  | 'u'
  | 'v'
  | 'w'
  | 'x'
  | 'y'
  | 'z';

/**
 * 嵌套语义槽的映射表。与 antd 的 `SemanticSchema` 同构。
 *
 * `_default: 'root'` 的语义（**逐条来自 antd 的 `mergeClassNames`**）：
 *   - 该键收到**普通对象** ⇒ 递归按子 schema 合并；
 *   - 该键收到**非对象**（字符串）⇒ 落到 `acc[key][_default]`（即 `classNames.popup = 'x'`
 *     ≡ `classNames.popup = { root: 'x' }`）；
 *   - **没有** `_default` 的子 schema（如 `image` 的 `placeholder: {}`）⇒ 只保证该键
 *     恒为对象（`fillObjectBySchema` 的 `||= {}`），不做字符串转换。
 */
export type SemanticSchema = { _default?: string } & {
  [key: `${LowerChar}${string}`]: SemanticSchema;
};

/**
 * 按**任意字符串键**读子 schema。
 *
 * ⚠️ 必须走这层 cast：`SemanticSchema` 的索引签名是 `` `${LowerChar}${string}` ``
 *    （antd 的 `ValidChar` 口径，见上面的注释），而 `Object.keys()` 给的是 `string`
 *    ⇒ 直接写 `schema[key]` 会 **TS7053**。这里的 cast 是**诚实的**：运行时 schema 的键
 *    本来就来自调用方写的对象字面量，`Object.keys` 拿到的正是那些键。
 */
function subSchema(schema: SemanticSchema, key: string): SemanticSchema | undefined {
  return (schema as Record<string, SemanticSchema | undefined>)[key];
}

/**
 * 按 schema 补齐对象结构（antd `fillObjectBySchema` 逐字）。
 *
 * 两条判据：
 *   ① `_default` 键 ⇒ `newObj[key] ||= {}`（保证**至少是空对象**，不会残留 `undefined`）；
 *   ② 其余子 schema ⇒ 递归（空 schema `{}` 会让该键变成 `{}`）。
 */
export function fillObjectBySchema(
  obj: Record<string, unknown> | undefined,
  schema: SemanticSchema,
): Record<string, unknown> {
  const newObj: Record<string, unknown> = { ...(obj ?? {}) };
  for (const key of Object.keys(schema)) {
    if (subSchema(schema, key)?._default) {
      newObj[key] ||= {};
    } else {
      newObj[key] = fillObjectBySchema(
        newObj[key] as Record<string, unknown> | undefined,
        subSchema(schema, key) as SemanticSchema,
      );
    }
  }
  return newObj;
}

/**
 * **带 schema** 的 classNames 合并（antd `mergeClassNames(schema, ...classNames)` 逐字）。
 *
 * ⚠️ 与下面**无 schema** 的 `mergeClassNames` 是**两条不同的语义**，不要合并：
 *    - 无 schema：只要有一侧是对象就**递归**（本仓在 select/auto-complete 期加的行为，
 *      比 antd 更宽松，且已被 7 个组件的既有用例钉住）；
 *    - 有 schema：**只有 schema 声明过的键**才特殊处理，其余键一律 `clsx` 平铺（antd 语义）。
 *
 *    两者的差别在「字符串 vs 对象混用」时可见：
 *      `classNames: { popup: 'x' }` 与 `{ popup: { root: 'y' } }` 两个来源
 *      —— schema 版给 `popup.root = 'x y'`（正确）；无 schema 版会把 `'x'` 当对象递归
 *      （`Object.keys('x')` ⇒ 垃圾键）。这正是 antd 需要 `_default` 的原因。
 */
export function mergeClassNamesBySchema<CN extends object>(
  schema: SemanticSchema,
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const keySchema = subSchema(schema, key);
      const cur = record[key];
      if (keySchema) {
        if (isPlainRecord(cur)) {
          acc[key] = mergeClassNamesBySchema(keySchema, (acc[key] ?? {}) as never, cur as never);
        } else {
          const defaultField = keySchema._default;
          if (defaultField) {
            const target = (acc[key] ?? {}) as Record<string, unknown>;
            target[defaultField] = clsx(
              target[defaultField] as string | undefined,
              cur as string | undefined,
            );
            acc[key] = target;
          }
        }
      } else {
        acc[key] = clsx(acc[key] as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

/**
 * 合并 styles。**逐键浅合并、后者胜** —— 注意与 classNames 的语义不同。
 *
 * 与 antd 的 `mergeStyles(...styles)` 等价。断言理由同 `mergeClassNames`。
 */
export function mergeStyles<ST extends object>(
  ...sources: readonly (Partial<ST> | undefined)[]
): Partial<ST> {
  const acc: Record<string, CSSProperties | undefined> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, CSSProperties | string | undefined>;
    for (const key of Object.keys(record)) {
      // 🚨 **叶子可能是 CSS 字符串**（Vue 的 `style` attr 允许字符串，而 `attrs.style`
      //    会经 `semanticRootStyle` 进到这里）。直接展开字符串会得到
      //    `{ 0: 'w', 1: 'i', … }` ⇒ Vue 的 `setStyle` 抛
      //    `'set' on proxy: trap returned falsish for property '0'`。
      acc[key] = { ...acc[key], ...normalizeStyleValue(record[key]) };
    }
  }
  return acc as Partial<ST>;
}

/**
 * `'width: 240px; color: red'` → `{ width: '240px', color: 'red' }`。
 *
 * ⚠️ 不引入 `@vue/shared` 的 `parseStringStyle`：它是 `vue` 的**传递依赖**，
 *    直接 import 属于幻影依赖（R7 的精神）。这里只需要支持 `;` 分隔的声明段，
 *    与 Vue 自己的实现判据一致（空段 / 无冒号的段跳过）。
 */
function parseStyleString(text: string): CSSProperties {
  const out: Record<string, string> = {};
  for (const part of text.split(';')) {
    const index = part.indexOf(':');
    if (index < 0) continue;
    const name = part.slice(0, index).trim();
    if (!name) continue;
    out[name] = part.slice(index + 1).trim();
  }
  return out as CSSProperties;
}

/** 样式叶子归一：字符串解析成对象，其余原样。 */
function normalizeStyleValue(value: CSSProperties | string | undefined): CSSProperties | undefined {
  if (typeof value === 'string') {
    return parseStyleString(value);
  }
  return value;
}

/**
 * 把平铺的 `style` 包成 `{ root: style }`。
 *
 * 与 antd 的 `useSemanticRootStyle(style, key = 'root')` 等价 —— 包括
 * 「`style` 为空时返回 `undefined` 而不是 `{ root: undefined }`」这一点：
 * 后者会让 `mergeStyles` 多产出一个 `root` 键，进而在 DOM 上多出一个空的 `style=""`。
 */
export function semanticRootStyle(
  style: CSSProperties | string | undefined,
  key = 'root',
): Record<string, CSSProperties> | undefined {
  if (!style) {
    return undefined;
  }
  // 🚨 `style` 可能是 **CSS 字符串**（`<Input style="width: 240px" />` —— Vue 的 `style`
  //    attr 两种形态都合法）。必须在这里解析成对象，否则下游 `mergeStyles` 的
  //    对象展开会把它拆成 `{ 0: 'w', … }`（Issue #7.1 实测）。
  return { [key]: typeof style === 'string' ? parseStyleString(style) : style };
}

/**
 * 把「可能为空的样式」转成可以直接 `v-bind` 的属性对象。
 *
 * 空样式返回 `{}`（**连 `style` 这个键都没有**），非空返回 `{ style }`。
 *
 * ── 为什么必须做这一步（2026-09-18，empty 实测）──────────────────────────────
 *
 * `mergeStyles()` 的返回值**恒**是对象（可能是 `{}`）。直接绑 `:style` 时：
 *
 * | 渲染路径 | 结果 |
 * |---|---|
 * | 客户端 | `patchStyle` 会把空样式移除 —— 没有 `style` 属性 ✓ |
 * | **SSR** | `ssrRenderAttrs` 对 `style` 键是**无条件**输出的 ⇒ 渲染出 `style=""` ✗ |
 *
 * React（antd）在样式为空时**不输出该属性**。所以 SSR 产物会与上游有差异，
 * 而且每个元素多 9 字节 —— 72 个组件 × 多层结构累积起来是可观的体积。
 *
 * 实测：Empty 一层就有 3 个元素带 `style=""`；改成 `v-bind="styleAttrs(x)"` 后归零。
 *
 * ⚠️ 这个差异 L4 **测不出来** —— 投影会把「没有 style 属性」与 `style=""`
 *    都归一化成空串（`(node.style ?? []).join(';')` 两边都是 `''`）。
 *    它是被渲染 SSR 预览页时肉眼发现的，所以既有 L1 断言也有这里。
 *
 * ⚠️ 所有用 `useMergeSemantic` 的组件都应该这样绑样式，而不是 `:style="mergedStyles.x"`。
 */
export function styleAttrs(style: CSSProperties | undefined): { style?: CSSProperties } {
  if (!style) return {};
  const record = style as Record<string, unknown>;
  for (const key of Object.keys(record)) {
    if (record[key] !== undefined) return { style };
  }
  return {};
}

export interface UseMergeSemanticResult<CN extends object, ST extends object> {
  classNames: ComputedRef<Partial<CN>>;
  styles: ComputedRef<Partial<ST>>;
}

/**
 * 响应式版本的 `useMergeSemantic`。
 *
 * 与 antd 的差别只有一处、且是平台差异（PLATFORM）：antd 每次渲染都重跑一遍合并，
 * 我们用 `computed` 缓存 —— 语义相同，但**依赖必须可追踪**，所以来源要用
 * `() => value` 的形式传，而不是先取值再传。
 *
 * @param classNamesSources 按优先级从低到高排列（后者拼接在前者之后）
 * @param stylesSources 按优先级从低到高排列（后者覆盖前者）
 * @param props 传给函数式变体的 `info.props`。**可以是 getter / ref** ——
 *   函数式变体每次重算都要看到**当前** props。传 `mergedProps.value` 那种
 *   setup 期快照会让 `disabled` / `size` / `variant` 变化后函数式仍按旧值计算
 *   （Issue #3.2）。裸对象仍然可用（`toValue` 原样返回）。
 * @param schema **嵌套语义槽**的映射表（antd 第四参）。给了它就会：
 *   ① classNames 走 `mergeClassNamesBySchema`（`_default` 的字符串→对象转换）；
 *   ② 两个结果都过一遍 `fillObjectBySchema`（保证嵌套键恒为对象）。
 *   ⚠️ 不给时**保持本仓既有行为**（无 schema 的递归合并）—— 7 个既有消费者不受影响。
 */
export function useMergeSemantic<P extends object, CN extends object, ST extends object>(
  classNamesSources: readonly MaybeSource<SemanticInput<Partial<CN>, P> | undefined>[],
  stylesSources: readonly MaybeSource<SemanticInput<Partial<ST>, P> | undefined>[],
  props: MaybeRefOrGetter<P>,
  schema?: SemanticSchema,
): UseMergeSemanticResult<CN, ST> {
  // ⚠️ `info` 必须在**每次重算时**新建，且 `props` 要在 computed 内 `toValue` ——
  //    在 setup 期建一次会把首帧的 props 快照焊死（Issue #3.2）。
  const classNames = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = classNamesSources.map((source) =>
      resolveSemantic<Partial<CN>, P>(toValue(source), info),
    );
    const merged = schema
      ? mergeClassNamesBySchema<CN>(schema, ...resolved)
      : mergeClassNames<CN>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<CN>;
  });

  const styles = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = stylesSources.map((source) =>
      resolveSemantic<Partial<ST>, P>(toValue(source), info),
    );
    const merged = mergeStyles<ST>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<ST>;
  });

  return { classNames, styles };
}
````

### ../../config-provider/size-context.ts

````ts
/**
 * `SizeContext` —— 组件尺寸。
 *
 * 契约来源：antd 6.6.4 的 `es/config-provider/SizeContext.tsx` + `hooks/useSize.ts`。
 *
 * ── 为什么它是**独立 context** 而不是 ConfigContext 的一个字段 ──────────────────
 *
 * antd 把它拆出去是为了「`componentSize` 变化时只重渲染读尺寸的组件」。
 * 本项目的理由更硬：`ConfigContextValue` 是**一个**响应式对象，任何字段变化都会
 * 触发所有读它的 `computed` 重算；而尺寸是被最多组件读的字段之一，独立出来能明显
 * 收窄依赖面。形态上也与 antd 对齐（便于迁移）。
 */

import { type ComputedRef, computed, type InjectionKey, inject } from 'vue';

/**
 * 尺寸。
 *
 * ⚠️ `'medium'` 与 `'middle'` **两个都要**：antd 6 起 `'medium'` 是推荐写法，
 * `'middle'` 仍是默认值且未移除（上游注释：`middle is deprecated and will be removed
 * in v7`）。`COMPONENT-RULES.md` §4 要求枚举值与 antd 一致 ⇒ 不裁剪成 `'medium'`。
 */
export type SizeType = 'small' | 'medium' | 'middle' | 'large';

/**
 * 注入键。
 *
 * 值是 `ComputedRef` 而不是裸值 —— 这样 `useSize` 在 `computed` 里读 `.value`
 * 会被追踪，`componentSize` 变化能传导到下游（对齐 antd 的 context 更新）。
 */
export const sizeContextKey: InjectionKey<ComputedRef<SizeType | undefined>> =
  Symbol('apolloSizeContext');

/**
 * 读取组件尺寸，与自己的 prop 合并。与 antd 的 `useSize` 逐字对应。
 *
 * 四条判据（逐条来自 `hooks/useSize.ts`）：
 *   1. `!customSize` ⇒ 用 context（⚠️ 真值判据：`0` / `''` 也走这一支）。
 *   2. `customSize` 是字符串 ⇒ `customSize ?? size`（字符串恒真，等价于直接返回）。
 *   3. `customSize` 是函数 ⇒ `customSize(size)`。
 *   4. 其余（数字 / 对象）⇒ 用 context。
 *
 * @example
 * ```ts
 * const mergedSize = useSize(props.size);   // ComputedRef<SizeType | undefined>
 * ```
 */
export function useSize<T extends string | number | undefined | object>(
  customSize?: T | ((ctxSize: SizeType | undefined) => T),
): ComputedRef<T | SizeType | undefined> {
  const injected = inject(sizeContextKey, undefined);

  return computed(() => {
    const ctxSize = injected?.value;

    if (!customSize) return ctxSize;

    if (typeof customSize === 'string') return customSize ?? ctxSize;

    if (typeof customSize === 'function') {
      return (customSize as (ctxSize: SizeType | undefined) => T)(ctxSize);
    }

    return ctxSize;
  });
}
````

### ../../select/interface.ts

```ts
/** Public Vue contracts for Select and its option data. */

import type { CSSProperties, VNodeChild } from 'vue';
import type { SizeType } from '../config-provider/size-context';

// ---------------------------------------------------------------------------
// 基础值类型
// ---------------------------------------------------------------------------

export type RawValueType = string | number;

/** antd 的 `SelectValue`。 */
export type SelectValue =
  | RawValueType
  | RawValueType[]
  | LabeledValue
  | LabeledValue[]
  | null
  | undefined;

/** antd 的 `LabeledValue`（labelInValue 的输出形态）。 */
export interface LabeledValue {
  key?: RawValueType;
  value: RawValueType;
  label?: unknown;
}

/** rc 的内部形态（`labelInValue` 的中间表示）。 */
export interface LabelInValueType {
  label?: unknown;
  value: RawValueType;
  key?: RawValueType;
  disabled?: boolean;
  title?: string;
}

export interface BaseOptionType {
  disabled?: boolean;
  className?: string;
  style?: CSSProperties;
  title?: string;
  [name: string]: unknown;
}

export interface DefaultOptionType extends BaseOptionType {
  label?: unknown;
  value?: RawValueType | null;
  children?: Omit<DefaultOptionType, 'children'>[];
  options?: DefaultOptionType[];
}

export type SelectOptionType = BaseOptionType | DefaultOptionType;

/** antd `OptionProps`（`Select.Option` / `Select.OptGroup`，deprecated 但保留）。 */
export interface OptionProps extends BaseOptionType {
  value?: RawValueType | null;
  children?: unknown;
}

export interface OptGroupProps extends BaseOptionType {
  label?: unknown;
  children?: unknown;
}

// ---------------------------------------------------------------------------
// 模式 / 尺寸 / 状态
// ---------------------------------------------------------------------------

/**
 * 公开模式只有 `multiple` / `tags` —— antd 把 `mode="combobox"` 吞成单选
 * （`index.tsx` 的 `mode` memo），只有 `SECRET_COMBOBOX_MODE_DO_NOT_USE` 才真走
 * combobox（AutoComplete 用）。内核实现 combobox 分支，公开类型不声明。
 */
export type SelectMode = 'multiple' | 'tags';

/** 内核模式（engine 内部用）。 */
export type InternalSelectMode = SelectMode | 'combobox';

/**
 * 尺寸。**直接别名到 `config-provider` 的 `SizeType`**（`'small' | 'medium' | 'middle' | 'large'`）。
 *
 * 上游 `SelectProps.size` 就是 `SizeType`；此前手抄成 `'small' | 'middle' | 'large'`
 * 漏了 `medium`（运行时 `useSize` 是吃 `SizeType` 的 ⇒ 类型比运行时窄，Issue #4.3）。
 */
export type SelectSize = SizeType;

export type SelectVariant = 'outlined' | 'borderless' | 'filled' | 'underlined';

export type SelectStatus = 'error' | 'warning' | 'success' | 'validating';

/** antd `SelectCommonPlacement`（`_util/motion.ts` 的 4 值）。 */
export type SelectCommonPlacement = 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight';

export type SelectDirection = 'ltr' | 'rtl';

// ---------------------------------------------------------------------------
// 搜索配置
// ---------------------------------------------------------------------------

export type FilterFunc<OptionType> = (inputValue: string, option: OptionType) => boolean;

export interface SearchConfig<OptionType = DefaultOptionType> {
  autoClearSearchValue?: boolean;
  filterOption?: boolean | FilterFunc<OptionType>;
  filterSort?: (optionA: OptionType, optionB: OptionType, info: { searchValue: string }) => number;
  optionFilterProp?: string | string[];
}

export type SelectSearchConfig = SearchConfig<DefaultOptionType>;

// ---------------------------------------------------------------------------
// 语义槽（classNames / styles）
// ---------------------------------------------------------------------------

export interface SelectSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: {
    root?: string;
    listItem?: string;
    list?: string;
  };
}

export interface SelectSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: {
    root?: CSSProperties;
    listItem?: CSSProperties;
    list?: CSSProperties;
  };
}

export interface FieldNames {
  value?: string;
  label?: string;
  groupLabel?: string;
  options?: string;
}

// ---------------------------------------------------------------------------
// Engine content function types; public component content uses slots.
// ---------------------------------------------------------------------------

/** `FlattenOptionData`（rc `interface.d.ts`）。 */
export interface FlattenOptionData<OptionType = DefaultOptionType> {
  label?: unknown;
  data: OptionType;
  key: string | number;
  value?: RawValueType;
  groupOption?: boolean;
  group?: boolean;
}

/** 选择器里一个已选值的展示形态（rc `DisplayValueType`）。 */
export interface DisplayValueType {
  key?: string | number;
  value?: RawValueType;
  label?: unknown;
  title?: unknown;
  disabled?: boolean;
  index?: number;
}

/** `tagRender` 的入参（rc `CustomTagProps`）。 */
export interface CustomTagProps {
  label?: unknown;
  value?: RawValueType;
  disabled: boolean;
  onClose: (event?: MouseEvent) => void;
  closable: boolean;
  isMaxTag: boolean;
  index?: number;
}

export type OptionRenderFn = (
  option: FlattenOptionData<DefaultOptionType>,
  info: { index: number },
) => VNodeChild;

export type LabelRenderFn = (props: LabelInValueType) => VNodeChild;

export type TagRenderFn = (props: CustomTagProps) => VNodeChild;

export type PopupRenderFn = (menu: unknown) => VNodeChild;

export type ScrollToArg =
  | number
  | {
      index?: number;
      align?: 'top' | 'bottom' | 'auto';
      key?: string | number;
    };

// ---------------------------------------------------------------------------
// 实例句柄（antd `RefSelectProps` = rc `BaseSelectRef`）
// ---------------------------------------------------------------------------

export interface SelectRef {
  focus: (options?: FocusOptions) => void;
  blur: () => void;
  scrollTo: (arg?: ScrollToArg) => void;
  nativeElement: HTMLElement | null;
}

// ---------------------------------------------------------------------------
// Props
// ---------------------------------------------------------------------------

export interface SelectProps<ValueType = SelectValue> {
  // ---- 身份 ----
  id?: string;
  prefixCls?: string;
  /** ⚠️ Vue 原生 `class` / `style` 走 attrs（不是 prop）；这里只为类型面留位。 */
  class?: unknown;

  // ---- 值 ----
  value?: ValueType;
  defaultValue?: ValueType;
  /** 输出 `{ label, value }` 而非裸值。 */
  labelInValue?: boolean;
  /** 回填值取 option 的哪个字段（默认 `label`）。 */
  optionLabelProp?: string;
  fieldNames?: FieldNames;

  // ---- 模式 ----
  mode?: SelectMode;

  // ---- 选项 ----
  options?: DefaultOptionType[];
  /** 搜索时列表的最大高度（默认 256）。 */
  listHeight?: number;
  /** 虚拟滚动的估算行高（默认 controlHeight = 32）。 */
  listItemHeight?: number;
  virtual?: boolean;
  /** 键盘上下键是否自动激活第一项（默认 true，combobox 为 false）。 */
  defaultActiveFirstOption?: boolean;
  // ---- 搜索 ----
  showSearch?: boolean | SelectSearchConfig;
  /** Search text; supports v-model:searchValue. */
  searchValue?: string;
  /** @deprecated 用 `showSearch.autoClearSearchValue` */
  autoClearSearchValue?: boolean;
  /** @deprecated 用 `showSearch.filterOption` */
  filterOption?: boolean | FilterFunc<DefaultOptionType>;
  /** @deprecated 用 `showSearch.filterSort` */
  filterSort?: SearchConfig<DefaultOptionType>['filterSort'];
  /** @deprecated 用 `showSearch.optionFilterProp` */
  optionFilterProp?: string | string[];

  // ---- 外观 ----
  size?: SelectSize;
  variant?: SelectVariant;
  /** @deprecated 用 `variant` */
  bordered?: boolean;
  status?: SelectStatus;
  disabled?: boolean;
  loading?: boolean;
  placeholder?: string;
  /** @deprecated 默认显示箭头，隐藏请用空的 `#suffixIcon` 插槽或 `showArrow: false` */
  showArrow?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild; label?: string };
  maxLength?: number;

  // ---- 多选 ----
  maxCount?: number;
  maxTagCount?: number;
  maxTagTextLength?: number;
  tokenSeparators?: string[] | ((input: string) => string[]);

  // ---- 浮层 ----
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  direction?: SelectDirection;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement | ShadowRoot;
  transitionName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  popupClassName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  dropdownClassName?: string;
  /** @deprecated 用 `styles.popup.root` */
  dropdownStyle?: CSSProperties;
  popupStyle?: CSSProperties;

  // ---- 语义槽 ----
  classNames?: SelectSemanticClassNames;
  styles?: SelectSemanticStyles;

  // ---- 无障碍 ----
  tabIndex?: number;
  autoFocus?: boolean;
  title?: string;
  role?: string;
}

// ---------------------------------------------------------------------------
// 事件（Vue 侧：语义事件 + v-model 同发，见 PITFALLS 162）
// ---------------------------------------------------------------------------

export interface SelectEmits<ValueType = SelectValue> {
  change: [value: ValueType, option: DefaultOptionType | DefaultOptionType[] | undefined];
  'update:value': [value: ValueType];
  select: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  deselect: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  search: [value: string];
  'update:searchValue': [value: string];
  openChange: [open: boolean];
  'update:open': [open: boolean];
  focus: [event: FocusEvent];
  blur: [event: FocusEvent];
  clear: [];
  popupScroll: [event: Event];
  inputKeyDown: [event: KeyboardEvent];
}

// ---------------------------------------------------------------------------
// Slots（规则 C8-R2：ReactNode / render prop 一律 slot —— **不**保留同名 prop。
// 文本类 prop（placeholder）保留 string 便捷形态，slot 优先。）
// ---------------------------------------------------------------------------

export interface SelectSlots {
  default?: () => VNodeChild;
  prefix?: () => VNodeChild;
  suffixIcon?: (props: {
    searchValue: string;
    open: boolean;
    focused: boolean;
    showSearch: boolean;
    loading?: boolean;
  }) => VNodeChild;
  searchIcon?: () => VNodeChild;
  loadingIcon?: () => VNodeChild;
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  menuItemSelectedIcon?: (props: {
    value?: unknown;
    disabled?: boolean;
    isSelected?: boolean;
  }) => VNodeChild;
  placeholder?: () => VNodeChild;
  notFoundContent?: () => VNodeChild;
  optionRender?: (props: {
    option: FlattenOptionData<DefaultOptionType>;
    index: number;
  }) => VNodeChild;
  tagRender?: (props: CustomTagProps) => VNodeChild;
  labelRender?: (props: LabelInValueType) => VNodeChild;
  popupRender?: (props: { menu: VNodeChild }) => VNodeChild;
  maxTagPlaceholder?: (props: { omittedValues: DisplayValueType[] }) => VNodeChild;
}
```

### ../hooks/search.ts

```ts
/**
 * Cascader 的搜索 hooks —— `useSearchConfig` / `useSearchOptions` 的 Vue 版。
 *
 * 判据（docs/analysis/cascader.md §3.4）：
 * - `showSearch` 为对象时合入默认配置（`matchInputWidth: true` / `limit: 50`）；
 * - `limit <= 0` 视为 false（不限制）；
 * - 过滤只在**叶子**（或 changeOnSelect / 多选的任意层）上做；命中的结果项用
 *   `render` 产出 label（antd 薄壳会注入带高亮的 render），并挂 `SEARCH_MARK`
 *   保存完整路径（展示与回填都需要它）；
 * - `sort` 提供时覆盖默认顺序。
 */

import { type ComputedRef, computed, type Ref } from 'vue';

import {
  type BaseOptionType,
  type FieldNames,
  type FilledFieldNames,
  fillFieldNames,
  getOptionChildren,
  getOptionLabel,
  getOptionValue,
  getSearchPath,
  SEARCH_MARK,
} from '../utils';

export interface SearchConfig {
  filter?: (
    searchValue: string,
    pathOptions: BaseOptionType[],
    fieldNames: { label: string },
  ) => boolean;
  render?: (
    inputValue: string,
    pathOptions: BaseOptionType[],
    prefixCls: string,
    fieldNames: FieldNames,
  ) => unknown;
  sort?: (
    a: BaseOptionType[],
    b: BaseOptionType[],
    searchValue: string,
    fieldNames: FieldNames,
  ) => number;
  matchInputWidth?: boolean;
  limit?: number | false;
  autoClearSearchValue?: boolean;
}

/** `showSearch` → [是否开启, 配置]（上游 useSearchConfig）。 */
export function normalizeSearchConfig(
  showSearch: boolean | Omit<SearchConfig, 'render'> | undefined,
  props: { autoClearSearchValue?: boolean },
): [boolean, SearchConfig] {
  if (!showSearch) return [false, {}];

  let searchConfig: SearchConfig = {
    matchInputWidth: true,
    limit: 50,
    autoClearSearchValue: props.autoClearSearchValue,
  };
  if (showSearch && typeof showSearch === 'object') {
    const {
      filter,
      sort,
      matchInputWidth = true,
      limit = 50,
      autoClearSearchValue = props.autoClearSearchValue,
    } = showSearch;
    searchConfig = { filter, sort, matchInputWidth, limit, autoClearSearchValue };
  }
  if (typeof searchConfig.limit === 'number' && searchConfig.limit <= 0) {
    searchConfig.limit = false;
  }
  return [true, searchConfig];
}

const defaultFilter = (
  search: string,
  options: BaseOptionType[],
  { label = '' }: { label?: string },
): boolean =>
  options.some((opt) =>
    String(opt[label] ?? '')
      .toLowerCase()
      .includes(search.toLowerCase()),
  );

const defaultRender = (
  _inputValue: string,
  path: BaseOptionType[],
  _prefixCls: string,
  fieldNames: FieldNames,
): unknown => {
  const fields = fillFieldNames(fieldNames);
  const labels = path.map((option) =>
    getOptionLabel(option, fields, getOptionValue(option, fields)),
  );
  return labels.every((label) => typeof label === 'string' || typeof label === 'number')
    ? labels.join(' / ')
    : labels.flatMap((label, index) => (index ? [' / ', label] : [label]));
};

/** 搜索态的候选 options（过滤 + render + limit + sort；上游 useSearchOptions）。 */
export function computeSearchOptions(
  search: string,
  options: BaseOptionType[],
  fieldNames: FilledFieldNames,
  prefixCls: string,
  config: SearchConfig,
  enableHalfPath: boolean,
): BaseOptionType[] {
  const { filter = defaultFilter, render = defaultRender, limit = 50, sort } = config;

  const filteredOptions: BaseOptionType[] = [];
  if (!search) return [];

  function dig(
    list: BaseOptionType[],
    pathOptions: BaseOptionType[],
    parentDisabled = false,
  ): void {
    list.forEach((option) => {
      // 无 sort 且有 limit 时攒够即停（上游的 perf saving）
      if (!sort && limit !== false && limit > 0 && filteredOptions.length >= limit) return;

      const connectedPathOptions = [...pathOptions, option];
      const children = getOptionChildren(option, fieldNames);
      const mergedDisabled = parentDisabled || !!option.disabled;

      // 只在叶子（或 changeOnSelect / 多选的任意层）上做过滤
      if (!children || children.length === 0 || enableHalfPath) {
        if (filter(search, connectedPathOptions, { label: fieldNames.label })) {
          filteredOptions.push({
            ...option,
            disabled: mergedDisabled,
            [fieldNames.label]: render(search, connectedPathOptions, prefixCls, {
              label: fieldNames.label,
              value: fieldNames.value,
              children: fieldNames.children,
            }),
            [SEARCH_MARK]: connectedPathOptions,
            [fieldNames.children]: undefined,
          });
        }
      }
      if (children) {
        dig(children, connectedPathOptions, mergedDisabled);
      }
    });
  }
  dig(options, []);

  if (sort) {
    filteredOptions.sort((a, b) =>
      sort(getSearchPath(a) ?? [], getSearchPath(b) ?? [], search, {
        label: fieldNames.label,
        value: fieldNames.value,
        children: fieldNames.children,
      }),
    );
  }
  return limit !== false && limit > 0 ? filteredOptions.slice(0, limit) : filteredOptions;
}

/** 响应式包装（供组件层使用）。 */
export function useSearchOptions(
  search: Ref<string>,
  options: ComputedRef<BaseOptionType[]>,
  fieldNames: Ref<FilledFieldNames>,
  prefixCls: Ref<string>,
  config: Ref<SearchConfig>,
  enableHalfPath: boolean,
): ComputedRef<BaseOptionType[]> {
  return computed(() =>
    computeSearchOptions(
      search.value,
      options.value,
      fieldNames.value,
      prefixCls.value,
      config.value,
      enableHalfPath,
    ),
  );
}
```

### ../utils.ts

```ts
import { isVNode, type VNodeChild } from 'vue';
import { convertDataToEntities, type DataEntity } from './engine/tree';

/** Internal path keys retain both the value type and path boundaries. */
export const SHOW_PARENT = 'SHOW_PARENT';
export const SHOW_CHILD = 'SHOW_CHILD';
export type ShowCheckedStrategy = typeof SHOW_PARENT | typeof SHOW_CHILD;
export interface FieldNames {
  label?: string;
  value?: string;
  children?: string;
}
export interface FilledFieldNames {
  label: string;
  value: string;
  key: string;
  children: string;
}
export type BaseOptionType = Record<string, unknown> & {
  disabled?: boolean;
  isLeaf?: boolean;
  loading?: boolean;
};
export type DefaultOptionType = BaseOptionType & {
  label?: VNodeChild;
  value?: string | number;
  children?: DefaultOptionType[];
};
export type ValueCell = (string | number)[];
export type RawValue = string | number | ValueCell;

export function toPathKey(value: ValueCell): string {
  return JSON.stringify(value);
}
export function toPathKeys(values: ValueCell[]): string[] {
  return values.map(toPathKey);
}
export function toPathValueStr(pathKey: string): string[] {
  const value: unknown = JSON.parse(pathKey);
  if (!Array.isArray(value) || !value.every(isValue))
    throw new TypeError('[Cascader] Invalid path key');
  return value.map(String);
}
export function fillFieldNames(fieldNames?: FieldNames): FilledFieldNames {
  const { label = 'label', value = 'value', children = 'children' } = fieldNames ?? {};
  return { label, value, key: value, children };
}
export function isValue(value: unknown): value is string | number {
  return typeof value === 'string' || typeof value === 'number';
}
export function getOptionValue(option: BaseOptionType, fields: FilledFieldNames): string | number {
  const value = option[fields.value];
  if (!isValue(value))
    throw new TypeError(`[Cascader] Option ${fields.value} must be a string or number`);
  return value;
}
export function isOption(value: unknown): value is BaseOptionType {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}
export function getOptionChildren(
  option: BaseOptionType | undefined,
  fields: FilledFieldNames,
): BaseOptionType[] {
  const children = option?.[fields.children];
  if (children === undefined || children === null) return [];
  if (!Array.isArray(children) || !children.every(isOption))
    throw new TypeError(`[Cascader] Option ${fields.children} must be an array of options`);
  return children;
}
export function getSearchPath(option: BaseOptionType): BaseOptionType[] | undefined {
  const path = option[SEARCH_MARK];
  return Array.isArray(path) && path.every(isOption) ? path : undefined;
}
export function toContent(value: unknown): VNodeChild {
  if (
    value === undefined ||
    value === null ||
    typeof value === 'string' ||
    typeof value === 'number' ||
    typeof value === 'boolean' ||
    isVNode(value)
  )
    return value;
  if (Array.isArray(value)) return value.map(toContent);
  throw new TypeError('[Cascader] Option labels must be Vue renderable content');
}
export function getOptionLabel(
  option: BaseOptionType | null,
  fields: FilledFieldNames,
  fallback: string | number,
): VNodeChild {
  const label = option?.[fields.label];
  return label === undefined ? fallback : toContent(label);
}
export function isLeaf(option: BaseOptionType | undefined, fields: FilledFieldNames): boolean {
  return option?.isLeaf ?? getOptionChildren(option, fields).length === 0;
}
export function scrollIntoParentView(element: HTMLElement): void {
  const parent = element.parentElement;
  if (!parent) return;
  const offset = element.offsetTop - parent.offsetTop;
  if (offset < parent.scrollTop) parent.scrollTo({ top: offset });
  else if (offset + element.clientHeight > parent.scrollTop + parent.clientHeight)
    parent.scrollTo({ top: offset + element.clientHeight - parent.clientHeight });
}
export const SEARCH_MARK = '__rc_cascader_search_mark__';
export function getFullPathKeys(
  options: BaseOptionType[],
  fields: FilledFieldNames,
): (ValueCell | undefined)[] {
  return options.map((option) =>
    getSearchPath(option)?.map((node) => getOptionValue(node, fields)),
  );
}
function isValueCell(value: unknown): value is ValueCell {
  return Array.isArray(value) && value.every(isValue);
}
export function toRawValues(value: RawValue | RawValue[] | undefined): ValueCell[] {
  if (value === undefined) return [];
  if (isValue(value)) return [[value]];
  if (!value.length) return [];
  if (isValueCell(value)) return [value];
  return value.map((path) => {
    if (!isValueCell(path))
      throw new TypeError('[Cascader] Values must be paths of strings or numbers');
    return path;
  });
}
export function formatStrategyValues(
  pathKeys: string[],
  getEntities: () => Record<string, DataEntity>,
  strategy: ShowCheckedStrategy,
): string[] {
  const checked = new Set(pathKeys);
  const entities = getEntities();
  return pathKeys.filter((key) => {
    const entity = Object.hasOwn(entities, key) ? entities[key] : undefined;
    if (entity?.node.disabled) return true;
    return strategy === SHOW_CHILD
      ? !entity?.children?.some((child) => checked.has(child.key))
      : !(entity?.parent && !entity.parent.node.disabled && checked.has(entity.parent.key));
  });
}
export interface PathOption {
  value: string | number;
  index: number;
  option: BaseOptionType | null;
}
export function toPathOptions(
  path: ValueCell,
  options: BaseOptionType[],
  fields: FilledFieldNames,
  stringMode = false,
): PathOption[] {
  let list = options;
  return path.map((value) => {
    const index = list.findIndex((option) =>
      stringMode ? String(option[fields.value]) === String(value) : option[fields.value] === value,
    );
    const option = list[index] ?? null;
    list = getOptionChildren(option ?? undefined, fields);
    return { value: option ? getOptionValue(option, fields) : value, index, option };
  });
}
export { convertDataToEntities };
```

### ../engine/tree.ts

```ts
/**
 * Cascader 依赖的两棵「树算法」—— `@rc-component/tree` 的 Vue 版移植。
 *
 * ── 为什么在这里，而不是独立包 ──────────────────────────────────────────────
 *
 * `foundation.json` 的开放决策 `early-extract-table-core-tree-core` 结论是
 * **A：不提前抽取独立包，等第二个消费者出现**。Cascader（多选的勾选传导）是第一个
 * 消费者，所以算法先落在 `cascader/engine/`；将来 Tree 组件需要时再按
 * `ActionButton` 那套做法提升到 `_internal/`（原位置留垫片）。
 *
 * ── 两个算法 ────────────────────────────────────────────────────────────────
 *
 * 1. `convertDataToEntities(dataNodes, config)` —— 把嵌套 options 摊成扁平实体表，
 *    并补出 `parent` / `children`（实体层面）与 `level` / `pos` / `nodes`（路径）。
 * 2. `conductCheck(keyList, checked, keyEntities)` —— 勾选传导：
 *    - `checked === true`（fill）：父选中 ⇒ 向下补全所有子；子全选 ⇒ 向上补父；
 *      部分选中 ⇒ 父记 halfChecked。
 *    - `checked === { checked: false, halfCheckedKeys }`（clean）：反向清理。
 *
 * 契约来源：`@rc-component/tree@1.x` 的 `es/utils/treeUtil.js`（convertDataToEntities /
 * traverseDataNodes）与 `es/utils/conductUtil.js`（conductCheck / fill+clean）。
 * 行为逐条对齐，**不复制源码**。
 */

/** 树节点实体。 */
export interface DataEntity {
  /** 原始节点。 */
  node: Record<string, unknown>;
  /** 从根到当前节点的原始节点链（Cascader 用它拼 pathKey）。 */
  nodes: Record<string, unknown>[];
  /** 在同级中的下标。 */
  index: number;
  /** 节点 key（`getKey(key, pos)`：key 缺失时回退 pos）。 */
  key: string;
  /** 位置串（形如 `0-1-2`）。 */
  pos: string;
  /** 层级（根为 0）。 */
  level: number;
  /** 父实体（根为 undefined）。 */
  parent?: DataEntity;
  /** 子实体列表（构造期填充）。 */
  children?: DataEntity[];
}

export interface Wrapper {
  posEntities: Record<string, DataEntity>;
  keyEntities: Record<string, DataEntity>;
  [key: string]: unknown;
}

export interface ConvertConfig {
  /** 用自定义字段解析（Cascader 传 `{ key: value字段, children }`）。 */
  fieldNames?: { key?: string; children?: string };
  /** 包装器扩展（Cascader 用它挂 `pathKeyEntities`）。 */
  initWrapper?: (wrapper: Wrapper) => Wrapper | undefined;
  /** 每个实体构造后的钩子（Cascader 用它把 key 覆写成 pathKey）。 */
  processEntity?: (entity: DataEntity, wrapper: Wrapper) => void;
  /** 全部处理完的钩子。 */
  onProcessFinished?: (wrapper: Wrapper) => void;
}

const DEFAULT_FIELD_NAMES = { key: 'key', children: 'children' };

function getPosition(level: string | number, index: number): string {
  return `${level}-${index}`;
}

function getKey(key: unknown, pos: string): string {
  return key !== null && key !== undefined ? String(key) : pos;
}

/**
 * 遍历嵌套数据（广度优先按层级展开，与上游同序）。
 *
 * ⚠️ 上游 `traverseDataNodes` 的 `nodes` 是**路径链**（根→当前），不是 children ——
 *    Cascader 的 typed value path 依赖完整的 nodes 路径。
 */
export function traverseDataNodes(
  dataNodes: Record<string, unknown>[],
  callback: (item: {
    node: Record<string, unknown>;
    index: number;
    pos: string;
    key: string;
    parentPos: string;
    level: number;
    nodes: Record<string, unknown>[];
  }) => void,
  config: ConvertConfig = {},
): void {
  const { key: fieldKey, children: fieldChildren } = {
    ...DEFAULT_FIELD_NAMES,
    ...(config.fieldNames ?? {}),
  };

  /**
   * @param level 本节点的 level；根调用传 **0** ⇒ 第一层节点的 level 为 0
   *              （rc-tree 的 level 从 0 起算）。⚠️ 不能用 `parentLevel + 1`
   *              的写法——虚拟根会把 -1 加成 0 再传给子，整体偏移一层。
   */
  function processNode(
    node: Record<string, unknown> | null,
    index: number,
    parent: { pos: string; level: number } | null,
    pathNodes: Record<string, unknown>[],
    level: number,
  ): void {
    const mergedParent = parent as { pos: string; level: number } | undefined;
    const children = (node ? node[fieldChildren] : dataNodes) as
      | Record<string, unknown>[]
      | undefined;
    // biome-ignore lint/style/noNonNullAssertion: node 非空时 mergedParent 必由调用方给出（pos/parentPos 都从它派生）
    const pos = node ? getPosition(mergedParent!.pos, index) : '0';
    const connectNodes = node ? [...pathNodes, node] : [];

    if (node) {
      callback({
        node,
        index,
        pos,
        key: getKey(node[fieldKey], pos),
        // biome-ignore lint/style/noNonNullAssertion: 同上 —— 这一支只在 node 非空时执行
        parentPos: mergedParent!.pos,
        level,
        nodes: connectNodes,
      });
    }

    (children ?? []).forEach((child, childIndex) => {
      processNode(child, childIndex, { pos, level }, connectNodes, level + 1);
    });
  }

  // ⚠️ 虚拟根的 level 是 **-1**：递归里 `level + 1` 后第一层节点的 level 才是 0
  //    （rc-tree 的 level 从 0 起算；传 0 会让整棵树偏移一层，conduct 的层级分组全错）
  processNode(null, 0, { pos: '0', level: -1 }, [], -1);
}

/**
 * 摊平嵌套数据为实体表。
 *
 * 与上游同构：同时产出 `posEntities` 与 `keyEntities`，`initWrapper` 可扩展包装器，
 * `processEntity` 在每个实体建好后回调（Cascader 借此把 `entity.key` 覆写成 pathKey）。
 */
export function convertDataToEntities(
  dataNodes: Record<string, unknown>[],
  config: ConvertConfig = {},
): Wrapper {
  const posEntities: Record<string, DataEntity> = {};
  const keyEntities: Record<string, DataEntity> = {};
  let wrapper: Wrapper = { posEntities, keyEntities };
  if (config.initWrapper) {
    wrapper = config.initWrapper(wrapper) ?? wrapper;
  }

  traverseDataNodes(
    dataNodes,
    (item) => {
      const { node, index, pos, key, parentPos, level, nodes } = item;
      const entity: DataEntity = { node, nodes, index, key, pos, level };
      const mergedKey = getKey(key, pos);

      Object.defineProperty(posEntities, pos, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });
      Object.defineProperty(keyEntities, mergedKey, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });

      entity.parent = Object.hasOwn(posEntities, parentPos) ? posEntities[parentPos] : undefined;
      if (entity.parent) {
        entity.parent.children = entity.parent.children || [];
        entity.parent.children.push(entity);
      }

      config.processEntity?.(entity, wrapper);
    },
    config,
  );

  config.onProcessFinished?.(wrapper);
  return wrapper;
}

// ================================ conduct ================================

export interface ConductResult {
  checkedKeys: string[];
  halfCheckedKeys: string[];
}

/** 上游 `isCheckDisabled`：`disabled` / `disableCheckbox` / `checkable === false`。 */
function isCheckDisabled(node: Record<string, unknown> | undefined): boolean {
  if (!node) return false;
  const { disabled, disableCheckbox, checkable } = node as {
    disabled?: boolean;
    disableCheckbox?: boolean;
    checkable?: boolean;
  };
  return !!(disabled || disableCheckbox) || checkable === false;
}

function removeFromCheckedKeys(
  halfCheckedKeys: Set<string>,
  checkedKeys: Set<string>,
): Set<string> {
  const filtered = new Set<string>();
  halfCheckedKeys.forEach((key) => {
    if (!checkedKeys.has(key)) filtered.add(key);
  });
  return filtered;
}

/** 按层级分组（上游 `conductCheck` 的第一步）。 */
function groupByLevel(keyEntities: Record<string, DataEntity>) {
  const levelEntities = new Map<number, Set<DataEntity>>();
  let maxLevel = 0;
  Object.keys(keyEntities).forEach((key) => {
    // noUncheckedIndexedAccess：索引访问可能 undefined（key 来自 Object.keys，防御式收窄）
    const entity = Object.hasOwn(keyEntities, key) ? keyEntities[key] : undefined;
    if (!entity) return;
    const { level } = entity;
    // ⚠️ 用局部变量接住（`get(...)!` 消不掉，且 `Map.get` 的返回类型永远是 `T | undefined`）
    let levelSet = levelEntities.get(level);
    if (!levelSet) {
      levelSet = new Set();
      levelEntities.set(level, levelSet);
    }
    levelSet.add(entity);
    maxLevel = Math.max(maxLevel, level);
  });
  return { levelEntities, maxLevel };
}

/** 自底向上：父的全部（非禁用）子是否都选中 / 部分选中。 */
function conductParent(
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  checkedKeys: Set<string>,
  halfCheckedKeys: Set<string>,
  getDisabled: (node: Record<string, unknown>) => boolean,
  onAllChecked: (parentKey: string) => void,
  onPartialChecked: (parentKey: string) => void,
): void {
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { node } = entity;
      const parent = entity.parent;
      if (!parent || getDisabled(node) || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const checked = checkedKeys.has(key);
          if (allChecked && !checked) allChecked = false;
          if (!partialChecked && (checked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (allChecked) onAllChecked(parent.key);
      if (partialChecked) onPartialChecked(parent.key);
      visitedKeys.add(parent.key);
    });
  }
}

function fillConductCheck(
  keys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  const halfCheckedKeys = new Set<string>();

  // 自顶向下：父选中 ⇒ 补子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (checkedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.add(childEntity.key);
          });
      }
    });
  }

  // 自底向上：子全选 ⇒ 补父；部分 ⇒ half
  conductParent(
    levelEntities,
    maxLevel,
    checkedKeys,
    halfCheckedKeys,
    getDisabled,
    (parentKey) => checkedKeys.add(parentKey),
    (parentKey) => halfCheckedKeys.add(parentKey),
  );

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

function cleanConductCheck(
  keys: Set<string>,
  halfKeys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  let halfCheckedKeys = new Set(halfKeys);

  // 自顶向下：未选中且非半选 ⇒ 清掉子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (!checkedKeys.has(key) && !halfCheckedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.delete(childEntity.key);
          });
      }
    });
  }

  // ⚠️ 自底向上必须**单遍**：`delete(parent.key)` 会立刻影响更高一层的判定
  //    （上游就是同一轮里先算 allChecked / partialChecked 再改 checkedKeys）。
  //    拆成两遍会让高层读到「本该删掉的父」，half 集合偏大。
  halfCheckedKeys = new Set<string>();
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { parent, node } = entity;
      if (getDisabled(node) || !parent || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const isChecked = checkedKeys.has(key);
          if (allChecked && !isChecked) allChecked = false;
          if (!partialChecked && (isChecked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (!allChecked) checkedKeys.delete(parent.key);
      if (partialChecked) halfCheckedKeys.add(parent.key);
      visitedKeys.add(parent.key);
    });
  }

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

/**
 * 勾选传导。
 *
 * @param keyList 当前 key 列表
 * @param checked `true` = fill（补全）；`{ checked: false, halfCheckedKeys }` = clean（清理）
 * @param keyEntities `convertDataToEntities` 产出的 `keyEntities`
 */
export function conductCheck(
  keyList: string[],
  checked: true | { checked: false; halfCheckedKeys: string[] },
  keyEntities: Record<string, DataEntity>,
  getCheckDisabled?: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const getDisabled = getCheckDisabled ?? isCheckDisabled;

  // 只处理存在的 key（上游会 warning 缺失的 key，本仓静默过滤）
  const keys = new Set(keyList.filter((key) => Object.hasOwn(keyEntities, key)));

  const { levelEntities, maxLevel } = groupByLevel(keyEntities);

  if (checked === true) {
    return fillConductCheck(keys, levelEntities, maxLevel, getDisabled);
  }
  return cleanConductCheck(
    keys,
    new Set(checked.halfCheckedKeys),
    levelEntities,
    maxLevel,
    getDisabled,
  );
}
```

## 语义化样式 (style-class)

用 `classNames` 给触发器根、后缀、内容、占位符和浮层列表挂语义类名，用 `styles` 注入内联样式；开关会切换圆角、背景、文字颜色与浮层列表样式。

绿色背景、文字与占位符使用成对的主题变量，在明暗外观下保留强调色与可读性。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo：classNames / styles 语义槽
import { Cascader, Switch, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';
import type { CascaderOutputValue } from '../interface';

const emphasize = ref(true);
const value = ref<CascaderOutputValue>([]);

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

const classNames = computed<Record<string, unknown>>(() => ({
  root: 'cascader-style-class-root',
  suffix: 'cascader-style-class-suffix',
  content: 'cascader-style-class-content',
  placeholder: 'cascader-style-class-placeholder',
  popup: {
    root: 'cascader-style-class-popup',
    list: 'cascader-style-class-list',
    listItem: 'cascader-style-class-list-item',
  },
}));

const styles = computed<Record<string, unknown>>(() => ({
  root: {
    borderRadius: emphasize.value ? '14px' : '8px',
    borderColor: emphasize.value
      ? 'var(--apollo-color-success-border)'
      : 'var(--apollo-color-border)',
    background: emphasize.value
      ? 'var(--apollo-color-success-bg)'
      : 'var(--apollo-color-bg-container)',
  },
  suffix: {
    color: emphasize.value
      ? 'var(--apollo-color-success-text)'
      : 'var(--apollo-color-text-tertiary)',
  },
  content: {
    fontWeight: emphasize.value ? '600' : '400',
    color: emphasize.value ? 'var(--apollo-color-success-text)' : 'var(--apollo-color-text)',
  },
  placeholder: {
    color: emphasize.value
      ? 'var(--apollo-color-success-text)'
      : 'var(--apollo-color-text-secondary)',
  },
  popup: {
    list: {
      backgroundColor: emphasize.value
        ? 'var(--apollo-color-success-bg)'
        : 'var(--apollo-color-bg-elevated)',
      padding: '6px',
    },
    listItem: {
      borderRadius: '8px',
      color: 'var(--apollo-color-text)',
    },
  },
}));
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 16px">
      <Switch v-model:checked="emphasize" aria-label="启用强调样式" />
      <span>强调样式</span>
      <Tag color="green">{{ emphasize ? '强调' : '素雅' }}</Tag>
    </div>

    <Cascader
      v-model:value="value"
      :options="options"
      :class-names="classNames"
      :styles="styles"
      placeholder="选择地区（语义样式）"
    />
  </div>
</template>

<style>
.cascader-style-class-popup {
  border: 1px solid var(--apollo-color-success-border);
}

.cascader-style-class-list {
  min-width: 132px;
}

.cascader-style-class-list-item {
  margin: 2px 0;
  transition: background-color 0.2s ease;
}

.cascader-style-class-root {
  transition: background-color 0.2s ease, border-color 0.2s ease;
}
</style>
```

### ../interface.ts

```ts
import type { CSSProperties, VNode, VNodeChild } from 'vue';
import type { SemanticInput } from '../_internal/use-merge-semantic';
import type { SizeType } from '../config-provider/size-context';
import type { SelectCommonPlacement, SelectSlots, SelectVariant } from '../select/interface';
import type { SearchConfig } from './hooks/search';
import type { BaseOptionType, FieldNames, RawValue, ShowCheckedStrategy, ValueCell } from './utils';

export type CascaderValue = RawValue | ValueCell[];
export type CascaderOutputValue = ValueCell | ValueCell[];
export type CascaderSelectedOptions = (BaseOptionType | null)[] | (BaseOptionType | null)[][];
export type CascaderSearchConfig = Omit<SearchConfig, 'render' | 'searchValue' | 'onSearch'>;
export interface CascaderSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: { root?: string; list?: string; listItem?: string };
}
export interface CascaderSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: { root?: CSSProperties; list?: CSSProperties; listItem?: CSSProperties };
}
export interface CascaderPanelProps {
  prefixCls?: string;
  options?: BaseOptionType[];
  value?: CascaderValue;
  defaultValue?: CascaderValue;
  multiple?: boolean;
  fieldNames?: FieldNames;
  changeOnSelect?: boolean;
  showCheckedStrategy?: ShowCheckedStrategy;
  loadData?: (selectedOptions: BaseOptionType[]) => void | Promise<void>;
  expandTrigger?: 'click' | 'hover';
  expandIcon?: VNodeChild;
  loadingIcon?: VNodeChild;
  direction?: 'ltr' | 'rtl';
  notFoundContent?: VNodeChild;
  disabled?: boolean;
  popupMenuColumnStyle?: CSSProperties;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderPanelProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderPanelProps>;
  'onUpdate:value'?: (value: CascaderOutputValue) => void;
  onChange?: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
}
export interface CascaderProps extends Omit<CascaderPanelProps, 'classNames' | 'styles'> {
  id?: string;
  checkable?: boolean;
  size?: SizeType;
  loading?: boolean;
  variant?: SelectVariant;
  bordered?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild };
  clearIcon?: VNodeChild;
  removeIcon?: VNodeChild;
  suffixIcon?: VNodeChild;
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  showSearch?: boolean | CascaderSearchConfig;
  searchValue?: string;
  autoClearSearchValue?: boolean;
  placeholder?: VNodeChild;
  popupClassName?: string;
  dropdownClassName?: string;
  popupStyle?: CSSProperties;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement;
  status?: 'error' | 'warning';
  maxTagCount?: number;
  maxTagTextLength?: number;
  maxTagPlaceholder?: VNodeChild;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderProps>;
  'onUpdate:open'?: (open: boolean) => void;
  'onUpdate:searchValue'?: (value: string) => void;
  onOpenChange?: (open: boolean) => void;
  onSearch?: (value: string) => void;
  onFocus?: (event: FocusEvent) => void;
  onBlur?: (event: FocusEvent) => void;
  onClear?: () => void;
  onPopupScroll?: (event: Event) => void;
  onKeydown?: (event: KeyboardEvent) => void;
  onKeyup?: (event: KeyboardEvent) => void;
  onMousedown?: (event: MouseEvent) => void;
}
export interface CascaderEmits {
  'update:value': (value: CascaderOutputValue) => void;
  change: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
  'update:open': (open: boolean) => void;
  openChange: (open: boolean) => void;
  'update:searchValue': (value: string) => void;
  search: (value: string) => void;
  focus: (event: FocusEvent) => void;
  blur: (event: FocusEvent) => void;
  clear: () => void;
  popupScroll: (event: Event) => void;
  keydown: (event: KeyboardEvent) => void;
  keyup: (event: KeyboardEvent) => void;
  mousedown: (event: MouseEvent) => void;
}
export interface CascaderOptionSlots {
  optionRender?: (scope: { option: BaseOptionType; pathOptions: BaseOptionType[] }) => VNodeChild;
  searchRender?: (scope: {
    inputValue: string;
    pathOptions: BaseOptionType[];
    fieldNames: FieldNames;
  }) => VNodeChild;
  expandIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
  loadingIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
}
export interface CascaderPanelSlots extends CascaderOptionSlots {
  notFoundContent?: () => VNodeChild;
}
export interface CascaderSlots extends CascaderPanelSlots {
  default?: () => VNodeChild;
  placeholder?: () => VNodeChild;
  displayRender?: (scope: {
    labels: VNodeChild[];
    selectedOptions: (BaseOptionType | null)[];
  }) => VNodeChild;
  suffixIcon?: SelectSlots['suffixIcon'];
  searchIcon?: SelectSlots['suffixIcon'];
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  maxTagPlaceholder?: (scope: {
    omittedValues: { value: ValueCell; label: VNodeChild; disabled?: boolean }[];
  }) => VNodeChild;
  popupRender?: (scope: { menu: VNode }) => VNodeChild;
}
export interface CascaderRef {
  readonly nativeElement: HTMLElement | null;
  focus: (options?: FocusOptions) => void;
  blur: () => void;
}
```

### ../../_internal/use-merge-semantic.ts

````ts
/**
 * 语义化 `classNames` / `styles` 的合并。
 *
 * 契约来源：antd 6.6.4 的 `es/_util/hooks/useMergeSemantic/index.js`（**逐条对齐**）。
 *
 * 为什么单独抽出来：72 个组件里有 60 多个都有 `classNames` / `styles`，合并语义
 * 一旦不一致，就会出现「Button 的覆盖优先级和 Empty 不一样」这类只有用户才会发现的问题。
 * 所以合并规则集中在这里，组件只声明「合并哪些来源、按什么顺序」。
 *
 * ── 与 antd 的对应关系（合并顺序是契约，不能改）────────────────────────────────
 *
 * ```
 * // antd（Empty）
 * const [mergedClassNames, mergedStyles] = useMergeSemantic(
 *   [contextClassNames, classNames],                          // classNamesList
 *   [contextStyles, contextStyleRoot, styles, styleRoot],     // stylesList
 *   { props },
 * );
 * ```
 *
 * 其中 `contextStyleRoot = useSemanticRootStyle(contextStyle)`、`styleRoot = useSemanticRootStyle(style)`，
 * 即把 `style` 这个平铺的 prop 包成 `{ root: style }` 再进合并。
 *
 * 三条必须逐字保留的判据：
 *   1. **classNames 是「拼接」不是「覆盖」** —— `clsx(acc[key], curVal)`，同名键会连起来。
 *   2. **styles 是「逐键浅合并、后者胜」** —— 与 classNames 不同，这里不是拼接。
 *   3. **`style` prop 排在 `styles.root` 之后** —— 所以 `style` 会**覆盖** `styles.root`。
 *      这条最反直觉，也最容易被「顺手改成更合理的顺序」。
 *
 * ── 函数式变体（裁决 `empty-semantic-fn` = B：支持）───────────────────────────
 *
 * antd 允许传 `(info: { props }) => 对象`。我们在 `resolveSemantic` 里逐字对应：
 * 判据是 `isFunction(value) ? value(info) : value`，**没有**额外的「只在需要时求值」优化
 * —— 那种优化会让函数式与对象式的行为出现差异。
 *
 * ── `schema`（嵌套语义槽）—— **2026-10-03 补齐** ──────────────────────────────
 *
 * antd 的第四参 `schema` 用 `_default` 把「字符串形态的嵌套键」落到指定子槽
 * （`classNames.popup = 'x'` ≡ `classNames.popup = { root: 'x' }`），并在最后用
 * `fillObjectBySchema` 保证嵌套键**恒为对象**。
 *
 * 本仓此前没有它，用「只要有一侧是对象就递归」绕过 —— 那在**字符串与对象混用**时
 * 会产垃圾键（`Object.keys('x')`）。antd 6.6.4 里 **9 个组件**传了 schema
 * （`select` / `cascader` / `color-picker` / `menu` / `tabs` / `image` / `splitter` /
 * `input.Search` / `table`），Table 是第一个**真的需要**它的（`body.cell` / `header.cell`）。
 *
 * ⚠️ **两条语义并存、不能合并**：不给 schema 时保持本仓既有行为（7 个消费者钉住它），
 *    给了 schema 才走 antd 的 `mergeClassNamesBySchema`。
 *    判据见 `__tests__/use-merge-semantic.test.ts` 的「反向哨兵」那一条。
 *
 * ── 这个模块没有证明什么 ──────────────────────────────────────────────────────
 *   - 没证明各组件的**合并顺序声明**是对的。本模块只保证「给定顺序，合并结果正确」；
 *     顺序本身由各组件的 compat 用例与 antd 对照（Empty 见 `__tests__/semantic.test.ts`）。
 *   - 没证明**所有该传 schema 的组件都传了**。schema 档 2026-10-03 实现，
 *     select / cascader / color-picker / tabs / image（×2）/ splitter 已补第四参；
 *     menu 无语义通道、`input.Search` 未实现（见 `docs/KNOWN-ISSUES.md` §2 留痕）。
 *
 *   ⚠️ 无 schema 的宽松路径（`mergeClassNames`）**仍在服务既有消费者**：它在
 *     「字符串 + 对象混用」时会产垃圾键（`Object.keys('x')`）。这条**曾**登记在
 *     `docs/KNOWN-ISSUES.md`，该文件的 §1 已于 2026-10-07 清零、登记项转入 §2 的
 *     「已修 / 已裁决」；但宽松路径本身**未改**（7 个既有消费者的用例钉住它）。
 *     若将来统一到 schema 档，需同步改这 7 处并重跑它们的 L4/L6。
 */

import { isFunction } from '@apollo-design/utils';
import {
  type ComputedRef,
  type CSSProperties,
  computed,
  type MaybeRefOrGetter,
  toValue,
} from 'vue';

/** 函数式语义化拿到的上下文。与 antd 的 `{ props }` 同构。 */
export interface SemanticInfo<P> {
  props: P;
}

/** 对象式或函数式的语义化输入。 */
export type SemanticInput<T, P> = T | ((info: SemanticInfo<P>) => T | undefined);

/** 任意可响应化的输入。普通值、ref、getter 都接受（与 `toValue` 同构）。 */
export type MaybeSource<T> = MaybeRefOrGetter<T>;

/**
 * ⚠️ **刻意不用** `_internal/clsx.ts` 那一份（2026-10-07 核对过）。
 *
 * 这里是**更窄**的语义：只保留字符串，数字 / 数组 / 对象一律丢弃。
 * 而共享层那份会展开数组与对象（`{a:true}` → `'a'`）。语义化 `classNames` 的槽位值
 * 本来就是字符串，宽版本在这里只会把「传错了形态」静默变成一个类名。
 * ⇒ 别为了「消重」把它换成共享版 —— 那份窄语义是有意的。
 */
function clsx(...values: unknown[]): string {
  return values.filter((v) => typeof v === 'string' && v !== '').join(' ');
}

/**
 * 求值一个语义化输入。
 *
 * 与 antd 的 `resolveStyleOrClass(value, info)` 逐字对应 —— 包括
 * **只在 `isFunction` 时求值**这一点：传 `null` / `undefined` 会原样返回，
 * 由下游的 `filter(Boolean)` 丢掉。
 */
export function resolveSemantic<T, P>(
  value: SemanticInput<T, P> | undefined | null,
  info: SemanticInfo<P>,
): T | undefined {
  if (value === undefined || value === null) return undefined;
  return isFunction(value) ? (value as (i: SemanticInfo<P>) => T | undefined)(info) : value;
}

/**
 * 合并 classNames。**拼接**语义：同名键连起来，不覆盖。
 *
 * 与 antd 的 `mergeClassNames(schema, ...classNames)` 在 `schema === undefined` 时等价。
 *
 * ⚠️ 实现里有一次类型断言（`as Record<string, string | undefined>`）。
 *    它**不是**类型漏洞，而是「语义键集合由调用方的泛型决定」这一事实的必然结果：
 *    函数体只做键的遍历与字符串拼接，不认识任何具体键。用 `as any` 才是漏洞，
 *    这里断言到的是精确的中间形态。
 */
export function mergeClassNames<CN extends object>(
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const cur = record[key];
      const prev = acc[key];
      // 嵌套语义对象（如 Select 的 classNames.popup.{root,list,listItem}）递归合并；
      // 叶子值按 clsx 拼接（select 期 AutoComplete 抓出：浅合并在 popup 上丢数据）
      if (isPlainRecord(cur) || isPlainRecord(prev)) {
        acc[key] = mergeClassNames((prev ?? {}) as never, (cur ?? {}) as never);
      } else {
        acc[key] = clsx(prev as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

function isPlainRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// ---------------------------------------------------------------------------
// schema（嵌套语义槽）—— antd `useMergeSemantic` 的第四参
// ---------------------------------------------------------------------------

/**
 * schema 的**键名首字符**集合。
 *
 * 与 antd 的 `ValidChar`（`_util/type.ts:91`）**逐字相同**：**只有小写 a–z**。
 * 这不是「随便写的」—— 它正是让 `_default`（下划线开头）**不落进**索引签名、
 * 从而不与 `{ _default?: string }` 冲突的机制。
 * ⇒ 别「顺手」把大写或下划线加进来（会让 `SemanticSchema` 立刻变成 `never` 交叉）。
 */
type LowerChar =
  | 'a'
  | 'b'
  | 'c'
  | 'd'
  | 'e'
  | 'f'
  | 'g'
  | 'h'
  | 'i'
  | 'j'
  | 'k'
  | 'l'
  | 'm'
  | 'n'
  | 'o'
  | 'p'
  | 'q'
  | 'r'
  | 's'
  | 't'
  | 'u'
  | 'v'
  | 'w'
  | 'x'
  | 'y'
  | 'z';

/**
 * 嵌套语义槽的映射表。与 antd 的 `SemanticSchema` 同构。
 *
 * `_default: 'root'` 的语义（**逐条来自 antd 的 `mergeClassNames`**）：
 *   - 该键收到**普通对象** ⇒ 递归按子 schema 合并；
 *   - 该键收到**非对象**（字符串）⇒ 落到 `acc[key][_default]`（即 `classNames.popup = 'x'`
 *     ≡ `classNames.popup = { root: 'x' }`）；
 *   - **没有** `_default` 的子 schema（如 `image` 的 `placeholder: {}`）⇒ 只保证该键
 *     恒为对象（`fillObjectBySchema` 的 `||= {}`），不做字符串转换。
 */
export type SemanticSchema = { _default?: string } & {
  [key: `${LowerChar}${string}`]: SemanticSchema;
};

/**
 * 按**任意字符串键**读子 schema。
 *
 * ⚠️ 必须走这层 cast：`SemanticSchema` 的索引签名是 `` `${LowerChar}${string}` ``
 *    （antd 的 `ValidChar` 口径，见上面的注释），而 `Object.keys()` 给的是 `string`
 *    ⇒ 直接写 `schema[key]` 会 **TS7053**。这里的 cast 是**诚实的**：运行时 schema 的键
 *    本来就来自调用方写的对象字面量，`Object.keys` 拿到的正是那些键。
 */
function subSchema(schema: SemanticSchema, key: string): SemanticSchema | undefined {
  return (schema as Record<string, SemanticSchema | undefined>)[key];
}

/**
 * 按 schema 补齐对象结构（antd `fillObjectBySchema` 逐字）。
 *
 * 两条判据：
 *   ① `_default` 键 ⇒ `newObj[key] ||= {}`（保证**至少是空对象**，不会残留 `undefined`）；
 *   ② 其余子 schema ⇒ 递归（空 schema `{}` 会让该键变成 `{}`）。
 */
export function fillObjectBySchema(
  obj: Record<string, unknown> | undefined,
  schema: SemanticSchema,
): Record<string, unknown> {
  const newObj: Record<string, unknown> = { ...(obj ?? {}) };
  for (const key of Object.keys(schema)) {
    if (subSchema(schema, key)?._default) {
      newObj[key] ||= {};
    } else {
      newObj[key] = fillObjectBySchema(
        newObj[key] as Record<string, unknown> | undefined,
        subSchema(schema, key) as SemanticSchema,
      );
    }
  }
  return newObj;
}

/**
 * **带 schema** 的 classNames 合并（antd `mergeClassNames(schema, ...classNames)` 逐字）。
 *
 * ⚠️ 与下面**无 schema** 的 `mergeClassNames` 是**两条不同的语义**，不要合并：
 *    - 无 schema：只要有一侧是对象就**递归**（本仓在 select/auto-complete 期加的行为，
 *      比 antd 更宽松，且已被 7 个组件的既有用例钉住）；
 *    - 有 schema：**只有 schema 声明过的键**才特殊处理，其余键一律 `clsx` 平铺（antd 语义）。
 *
 *    两者的差别在「字符串 vs 对象混用」时可见：
 *      `classNames: { popup: 'x' }` 与 `{ popup: { root: 'y' } }` 两个来源
 *      —— schema 版给 `popup.root = 'x y'`（正确）；无 schema 版会把 `'x'` 当对象递归
 *      （`Object.keys('x')` ⇒ 垃圾键）。这正是 antd 需要 `_default` 的原因。
 */
export function mergeClassNamesBySchema<CN extends object>(
  schema: SemanticSchema,
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const keySchema = subSchema(schema, key);
      const cur = record[key];
      if (keySchema) {
        if (isPlainRecord(cur)) {
          acc[key] = mergeClassNamesBySchema(keySchema, (acc[key] ?? {}) as never, cur as never);
        } else {
          const defaultField = keySchema._default;
          if (defaultField) {
            const target = (acc[key] ?? {}) as Record<string, unknown>;
            target[defaultField] = clsx(
              target[defaultField] as string | undefined,
              cur as string | undefined,
            );
            acc[key] = target;
          }
        }
      } else {
        acc[key] = clsx(acc[key] as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

/**
 * 合并 styles。**逐键浅合并、后者胜** —— 注意与 classNames 的语义不同。
 *
 * 与 antd 的 `mergeStyles(...styles)` 等价。断言理由同 `mergeClassNames`。
 */
export function mergeStyles<ST extends object>(
  ...sources: readonly (Partial<ST> | undefined)[]
): Partial<ST> {
  const acc: Record<string, CSSProperties | undefined> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, CSSProperties | string | undefined>;
    for (const key of Object.keys(record)) {
      // 🚨 **叶子可能是 CSS 字符串**（Vue 的 `style` attr 允许字符串，而 `attrs.style`
      //    会经 `semanticRootStyle` 进到这里）。直接展开字符串会得到
      //    `{ 0: 'w', 1: 'i', … }` ⇒ Vue 的 `setStyle` 抛
      //    `'set' on proxy: trap returned falsish for property '0'`。
      acc[key] = { ...acc[key], ...normalizeStyleValue(record[key]) };
    }
  }
  return acc as Partial<ST>;
}

/**
 * `'width: 240px; color: red'` → `{ width: '240px', color: 'red' }`。
 *
 * ⚠️ 不引入 `@vue/shared` 的 `parseStringStyle`：它是 `vue` 的**传递依赖**，
 *    直接 import 属于幻影依赖（R7 的精神）。这里只需要支持 `;` 分隔的声明段，
 *    与 Vue 自己的实现判据一致（空段 / 无冒号的段跳过）。
 */
function parseStyleString(text: string): CSSProperties {
  const out: Record<string, string> = {};
  for (const part of text.split(';')) {
    const index = part.indexOf(':');
    if (index < 0) continue;
    const name = part.slice(0, index).trim();
    if (!name) continue;
    out[name] = part.slice(index + 1).trim();
  }
  return out as CSSProperties;
}

/** 样式叶子归一：字符串解析成对象，其余原样。 */
function normalizeStyleValue(value: CSSProperties | string | undefined): CSSProperties | undefined {
  if (typeof value === 'string') {
    return parseStyleString(value);
  }
  return value;
}

/**
 * 把平铺的 `style` 包成 `{ root: style }`。
 *
 * 与 antd 的 `useSemanticRootStyle(style, key = 'root')` 等价 —— 包括
 * 「`style` 为空时返回 `undefined` 而不是 `{ root: undefined }`」这一点：
 * 后者会让 `mergeStyles` 多产出一个 `root` 键，进而在 DOM 上多出一个空的 `style=""`。
 */
export function semanticRootStyle(
  style: CSSProperties | string | undefined,
  key = 'root',
): Record<string, CSSProperties> | undefined {
  if (!style) {
    return undefined;
  }
  // 🚨 `style` 可能是 **CSS 字符串**（`<Input style="width: 240px" />` —— Vue 的 `style`
  //    attr 两种形态都合法）。必须在这里解析成对象，否则下游 `mergeStyles` 的
  //    对象展开会把它拆成 `{ 0: 'w', … }`（Issue #7.1 实测）。
  return { [key]: typeof style === 'string' ? parseStyleString(style) : style };
}

/**
 * 把「可能为空的样式」转成可以直接 `v-bind` 的属性对象。
 *
 * 空样式返回 `{}`（**连 `style` 这个键都没有**），非空返回 `{ style }`。
 *
 * ── 为什么必须做这一步（2026-09-18，empty 实测）──────────────────────────────
 *
 * `mergeStyles()` 的返回值**恒**是对象（可能是 `{}`）。直接绑 `:style` 时：
 *
 * | 渲染路径 | 结果 |
 * |---|---|
 * | 客户端 | `patchStyle` 会把空样式移除 —— 没有 `style` 属性 ✓ |
 * | **SSR** | `ssrRenderAttrs` 对 `style` 键是**无条件**输出的 ⇒ 渲染出 `style=""` ✗ |
 *
 * React（antd）在样式为空时**不输出该属性**。所以 SSR 产物会与上游有差异，
 * 而且每个元素多 9 字节 —— 72 个组件 × 多层结构累积起来是可观的体积。
 *
 * 实测：Empty 一层就有 3 个元素带 `style=""`；改成 `v-bind="styleAttrs(x)"` 后归零。
 *
 * ⚠️ 这个差异 L4 **测不出来** —— 投影会把「没有 style 属性」与 `style=""`
 *    都归一化成空串（`(node.style ?? []).join(';')` 两边都是 `''`）。
 *    它是被渲染 SSR 预览页时肉眼发现的，所以既有 L1 断言也有这里。
 *
 * ⚠️ 所有用 `useMergeSemantic` 的组件都应该这样绑样式，而不是 `:style="mergedStyles.x"`。
 */
export function styleAttrs(style: CSSProperties | undefined): { style?: CSSProperties } {
  if (!style) return {};
  const record = style as Record<string, unknown>;
  for (const key of Object.keys(record)) {
    if (record[key] !== undefined) return { style };
  }
  return {};
}

export interface UseMergeSemanticResult<CN extends object, ST extends object> {
  classNames: ComputedRef<Partial<CN>>;
  styles: ComputedRef<Partial<ST>>;
}

/**
 * 响应式版本的 `useMergeSemantic`。
 *
 * 与 antd 的差别只有一处、且是平台差异（PLATFORM）：antd 每次渲染都重跑一遍合并，
 * 我们用 `computed` 缓存 —— 语义相同，但**依赖必须可追踪**，所以来源要用
 * `() => value` 的形式传，而不是先取值再传。
 *
 * @param classNamesSources 按优先级从低到高排列（后者拼接在前者之后）
 * @param stylesSources 按优先级从低到高排列（后者覆盖前者）
 * @param props 传给函数式变体的 `info.props`。**可以是 getter / ref** ——
 *   函数式变体每次重算都要看到**当前** props。传 `mergedProps.value` 那种
 *   setup 期快照会让 `disabled` / `size` / `variant` 变化后函数式仍按旧值计算
 *   （Issue #3.2）。裸对象仍然可用（`toValue` 原样返回）。
 * @param schema **嵌套语义槽**的映射表（antd 第四参）。给了它就会：
 *   ① classNames 走 `mergeClassNamesBySchema`（`_default` 的字符串→对象转换）；
 *   ② 两个结果都过一遍 `fillObjectBySchema`（保证嵌套键恒为对象）。
 *   ⚠️ 不给时**保持本仓既有行为**（无 schema 的递归合并）—— 7 个既有消费者不受影响。
 */
export function useMergeSemantic<P extends object, CN extends object, ST extends object>(
  classNamesSources: readonly MaybeSource<SemanticInput<Partial<CN>, P> | undefined>[],
  stylesSources: readonly MaybeSource<SemanticInput<Partial<ST>, P> | undefined>[],
  props: MaybeRefOrGetter<P>,
  schema?: SemanticSchema,
): UseMergeSemanticResult<CN, ST> {
  // ⚠️ `info` 必须在**每次重算时**新建，且 `props` 要在 computed 内 `toValue` ——
  //    在 setup 期建一次会把首帧的 props 快照焊死（Issue #3.2）。
  const classNames = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = classNamesSources.map((source) =>
      resolveSemantic<Partial<CN>, P>(toValue(source), info),
    );
    const merged = schema
      ? mergeClassNamesBySchema<CN>(schema, ...resolved)
      : mergeClassNames<CN>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<CN>;
  });

  const styles = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = stylesSources.map((source) =>
      resolveSemantic<Partial<ST>, P>(toValue(source), info),
    );
    const merged = mergeStyles<ST>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<ST>;
  });

  return { classNames, styles };
}
````

### ../../config-provider/size-context.ts

````ts
/**
 * `SizeContext` —— 组件尺寸。
 *
 * 契约来源：antd 6.6.4 的 `es/config-provider/SizeContext.tsx` + `hooks/useSize.ts`。
 *
 * ── 为什么它是**独立 context** 而不是 ConfigContext 的一个字段 ──────────────────
 *
 * antd 把它拆出去是为了「`componentSize` 变化时只重渲染读尺寸的组件」。
 * 本项目的理由更硬：`ConfigContextValue` 是**一个**响应式对象，任何字段变化都会
 * 触发所有读它的 `computed` 重算；而尺寸是被最多组件读的字段之一，独立出来能明显
 * 收窄依赖面。形态上也与 antd 对齐（便于迁移）。
 */

import { type ComputedRef, computed, type InjectionKey, inject } from 'vue';

/**
 * 尺寸。
 *
 * ⚠️ `'medium'` 与 `'middle'` **两个都要**：antd 6 起 `'medium'` 是推荐写法，
 * `'middle'` 仍是默认值且未移除（上游注释：`middle is deprecated and will be removed
 * in v7`）。`COMPONENT-RULES.md` §4 要求枚举值与 antd 一致 ⇒ 不裁剪成 `'medium'`。
 */
export type SizeType = 'small' | 'medium' | 'middle' | 'large';

/**
 * 注入键。
 *
 * 值是 `ComputedRef` 而不是裸值 —— 这样 `useSize` 在 `computed` 里读 `.value`
 * 会被追踪，`componentSize` 变化能传导到下游（对齐 antd 的 context 更新）。
 */
export const sizeContextKey: InjectionKey<ComputedRef<SizeType | undefined>> =
  Symbol('apolloSizeContext');

/**
 * 读取组件尺寸，与自己的 prop 合并。与 antd 的 `useSize` 逐字对应。
 *
 * 四条判据（逐条来自 `hooks/useSize.ts`）：
 *   1. `!customSize` ⇒ 用 context（⚠️ 真值判据：`0` / `''` 也走这一支）。
 *   2. `customSize` 是字符串 ⇒ `customSize ?? size`（字符串恒真，等价于直接返回）。
 *   3. `customSize` 是函数 ⇒ `customSize(size)`。
 *   4. 其余（数字 / 对象）⇒ 用 context。
 *
 * @example
 * ```ts
 * const mergedSize = useSize(props.size);   // ComputedRef<SizeType | undefined>
 * ```
 */
export function useSize<T extends string | number | undefined | object>(
  customSize?: T | ((ctxSize: SizeType | undefined) => T),
): ComputedRef<T | SizeType | undefined> {
  const injected = inject(sizeContextKey, undefined);

  return computed(() => {
    const ctxSize = injected?.value;

    if (!customSize) return ctxSize;

    if (typeof customSize === 'string') return customSize ?? ctxSize;

    if (typeof customSize === 'function') {
      return (customSize as (ctxSize: SizeType | undefined) => T)(ctxSize);
    }

    return ctxSize;
  });
}
````

### ../../select/interface.ts

```ts
/** Public Vue contracts for Select and its option data. */

import type { CSSProperties, VNodeChild } from 'vue';
import type { SizeType } from '../config-provider/size-context';

// ---------------------------------------------------------------------------
// 基础值类型
// ---------------------------------------------------------------------------

export type RawValueType = string | number;

/** antd 的 `SelectValue`。 */
export type SelectValue =
  | RawValueType
  | RawValueType[]
  | LabeledValue
  | LabeledValue[]
  | null
  | undefined;

/** antd 的 `LabeledValue`（labelInValue 的输出形态）。 */
export interface LabeledValue {
  key?: RawValueType;
  value: RawValueType;
  label?: unknown;
}

/** rc 的内部形态（`labelInValue` 的中间表示）。 */
export interface LabelInValueType {
  label?: unknown;
  value: RawValueType;
  key?: RawValueType;
  disabled?: boolean;
  title?: string;
}

export interface BaseOptionType {
  disabled?: boolean;
  className?: string;
  style?: CSSProperties;
  title?: string;
  [name: string]: unknown;
}

export interface DefaultOptionType extends BaseOptionType {
  label?: unknown;
  value?: RawValueType | null;
  children?: Omit<DefaultOptionType, 'children'>[];
  options?: DefaultOptionType[];
}

export type SelectOptionType = BaseOptionType | DefaultOptionType;

/** antd `OptionProps`（`Select.Option` / `Select.OptGroup`，deprecated 但保留）。 */
export interface OptionProps extends BaseOptionType {
  value?: RawValueType | null;
  children?: unknown;
}

export interface OptGroupProps extends BaseOptionType {
  label?: unknown;
  children?: unknown;
}

// ---------------------------------------------------------------------------
// 模式 / 尺寸 / 状态
// ---------------------------------------------------------------------------

/**
 * 公开模式只有 `multiple` / `tags` —— antd 把 `mode="combobox"` 吞成单选
 * （`index.tsx` 的 `mode` memo），只有 `SECRET_COMBOBOX_MODE_DO_NOT_USE` 才真走
 * combobox（AutoComplete 用）。内核实现 combobox 分支，公开类型不声明。
 */
export type SelectMode = 'multiple' | 'tags';

/** 内核模式（engine 内部用）。 */
export type InternalSelectMode = SelectMode | 'combobox';

/**
 * 尺寸。**直接别名到 `config-provider` 的 `SizeType`**（`'small' | 'medium' | 'middle' | 'large'`）。
 *
 * 上游 `SelectProps.size` 就是 `SizeType`；此前手抄成 `'small' | 'middle' | 'large'`
 * 漏了 `medium`（运行时 `useSize` 是吃 `SizeType` 的 ⇒ 类型比运行时窄，Issue #4.3）。
 */
export type SelectSize = SizeType;

export type SelectVariant = 'outlined' | 'borderless' | 'filled' | 'underlined';

export type SelectStatus = 'error' | 'warning' | 'success' | 'validating';

/** antd `SelectCommonPlacement`（`_util/motion.ts` 的 4 值）。 */
export type SelectCommonPlacement = 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight';

export type SelectDirection = 'ltr' | 'rtl';

// ---------------------------------------------------------------------------
// 搜索配置
// ---------------------------------------------------------------------------

export type FilterFunc<OptionType> = (inputValue: string, option: OptionType) => boolean;

export interface SearchConfig<OptionType = DefaultOptionType> {
  autoClearSearchValue?: boolean;
  filterOption?: boolean | FilterFunc<OptionType>;
  filterSort?: (optionA: OptionType, optionB: OptionType, info: { searchValue: string }) => number;
  optionFilterProp?: string | string[];
}

export type SelectSearchConfig = SearchConfig<DefaultOptionType>;

// ---------------------------------------------------------------------------
// 语义槽（classNames / styles）
// ---------------------------------------------------------------------------

export interface SelectSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: {
    root?: string;
    listItem?: string;
    list?: string;
  };
}

export interface SelectSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: {
    root?: CSSProperties;
    listItem?: CSSProperties;
    list?: CSSProperties;
  };
}

export interface FieldNames {
  value?: string;
  label?: string;
  groupLabel?: string;
  options?: string;
}

// ---------------------------------------------------------------------------
// Engine content function types; public component content uses slots.
// ---------------------------------------------------------------------------

/** `FlattenOptionData`（rc `interface.d.ts`）。 */
export interface FlattenOptionData<OptionType = DefaultOptionType> {
  label?: unknown;
  data: OptionType;
  key: string | number;
  value?: RawValueType;
  groupOption?: boolean;
  group?: boolean;
}

/** 选择器里一个已选值的展示形态（rc `DisplayValueType`）。 */
export interface DisplayValueType {
  key?: string | number;
  value?: RawValueType;
  label?: unknown;
  title?: unknown;
  disabled?: boolean;
  index?: number;
}

/** `tagRender` 的入参（rc `CustomTagProps`）。 */
export interface CustomTagProps {
  label?: unknown;
  value?: RawValueType;
  disabled: boolean;
  onClose: (event?: MouseEvent) => void;
  closable: boolean;
  isMaxTag: boolean;
  index?: number;
}

export type OptionRenderFn = (
  option: FlattenOptionData<DefaultOptionType>,
  info: { index: number },
) => VNodeChild;

export type LabelRenderFn = (props: LabelInValueType) => VNodeChild;

export type TagRenderFn = (props: CustomTagProps) => VNodeChild;

export type PopupRenderFn = (menu: unknown) => VNodeChild;

export type ScrollToArg =
  | number
  | {
      index?: number;
      align?: 'top' | 'bottom' | 'auto';
      key?: string | number;
    };

// ---------------------------------------------------------------------------
// 实例句柄（antd `RefSelectProps` = rc `BaseSelectRef`）
// ---------------------------------------------------------------------------

export interface SelectRef {
  focus: (options?: FocusOptions) => void;
  blur: () => void;
  scrollTo: (arg?: ScrollToArg) => void;
  nativeElement: HTMLElement | null;
}

// ---------------------------------------------------------------------------
// Props
// ---------------------------------------------------------------------------

export interface SelectProps<ValueType = SelectValue> {
  // ---- 身份 ----
  id?: string;
  prefixCls?: string;
  /** ⚠️ Vue 原生 `class` / `style` 走 attrs（不是 prop）；这里只为类型面留位。 */
  class?: unknown;

  // ---- 值 ----
  value?: ValueType;
  defaultValue?: ValueType;
  /** 输出 `{ label, value }` 而非裸值。 */
  labelInValue?: boolean;
  /** 回填值取 option 的哪个字段（默认 `label`）。 */
  optionLabelProp?: string;
  fieldNames?: FieldNames;

  // ---- 模式 ----
  mode?: SelectMode;

  // ---- 选项 ----
  options?: DefaultOptionType[];
  /** 搜索时列表的最大高度（默认 256）。 */
  listHeight?: number;
  /** 虚拟滚动的估算行高（默认 controlHeight = 32）。 */
  listItemHeight?: number;
  virtual?: boolean;
  /** 键盘上下键是否自动激活第一项（默认 true，combobox 为 false）。 */
  defaultActiveFirstOption?: boolean;
  // ---- 搜索 ----
  showSearch?: boolean | SelectSearchConfig;
  /** Search text; supports v-model:searchValue. */
  searchValue?: string;
  /** @deprecated 用 `showSearch.autoClearSearchValue` */
  autoClearSearchValue?: boolean;
  /** @deprecated 用 `showSearch.filterOption` */
  filterOption?: boolean | FilterFunc<DefaultOptionType>;
  /** @deprecated 用 `showSearch.filterSort` */
  filterSort?: SearchConfig<DefaultOptionType>['filterSort'];
  /** @deprecated 用 `showSearch.optionFilterProp` */
  optionFilterProp?: string | string[];

  // ---- 外观 ----
  size?: SelectSize;
  variant?: SelectVariant;
  /** @deprecated 用 `variant` */
  bordered?: boolean;
  status?: SelectStatus;
  disabled?: boolean;
  loading?: boolean;
  placeholder?: string;
  /** @deprecated 默认显示箭头，隐藏请用空的 `#suffixIcon` 插槽或 `showArrow: false` */
  showArrow?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild; label?: string };
  maxLength?: number;

  // ---- 多选 ----
  maxCount?: number;
  maxTagCount?: number;
  maxTagTextLength?: number;
  tokenSeparators?: string[] | ((input: string) => string[]);

  // ---- 浮层 ----
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  direction?: SelectDirection;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement | ShadowRoot;
  transitionName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  popupClassName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  dropdownClassName?: string;
  /** @deprecated 用 `styles.popup.root` */
  dropdownStyle?: CSSProperties;
  popupStyle?: CSSProperties;

  // ---- 语义槽 ----
  classNames?: SelectSemanticClassNames;
  styles?: SelectSemanticStyles;

  // ---- 无障碍 ----
  tabIndex?: number;
  autoFocus?: boolean;
  title?: string;
  role?: string;
}

// ---------------------------------------------------------------------------
// 事件（Vue 侧：语义事件 + v-model 同发，见 PITFALLS 162）
// ---------------------------------------------------------------------------

export interface SelectEmits<ValueType = SelectValue> {
  change: [value: ValueType, option: DefaultOptionType | DefaultOptionType[] | undefined];
  'update:value': [value: ValueType];
  select: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  deselect: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  search: [value: string];
  'update:searchValue': [value: string];
  openChange: [open: boolean];
  'update:open': [open: boolean];
  focus: [event: FocusEvent];
  blur: [event: FocusEvent];
  clear: [];
  popupScroll: [event: Event];
  inputKeyDown: [event: KeyboardEvent];
}

// ---------------------------------------------------------------------------
// Slots（规则 C8-R2：ReactNode / render prop 一律 slot —— **不**保留同名 prop。
// 文本类 prop（placeholder）保留 string 便捷形态，slot 优先。）
// ---------------------------------------------------------------------------

export interface SelectSlots {
  default?: () => VNodeChild;
  prefix?: () => VNodeChild;
  suffixIcon?: (props: {
    searchValue: string;
    open: boolean;
    focused: boolean;
    showSearch: boolean;
    loading?: boolean;
  }) => VNodeChild;
  searchIcon?: () => VNodeChild;
  loadingIcon?: () => VNodeChild;
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  menuItemSelectedIcon?: (props: {
    value?: unknown;
    disabled?: boolean;
    isSelected?: boolean;
  }) => VNodeChild;
  placeholder?: () => VNodeChild;
  notFoundContent?: () => VNodeChild;
  optionRender?: (props: {
    option: FlattenOptionData<DefaultOptionType>;
    index: number;
  }) => VNodeChild;
  tagRender?: (props: CustomTagProps) => VNodeChild;
  labelRender?: (props: LabelInValueType) => VNodeChild;
  popupRender?: (props: { menu: VNodeChild }) => VNodeChild;
  maxTagPlaceholder?: (props: { omittedValues: DisplayValueType[] }) => VNodeChild;
}
```

### ../hooks/search.ts

```ts
/**
 * Cascader 的搜索 hooks —— `useSearchConfig` / `useSearchOptions` 的 Vue 版。
 *
 * 判据（docs/analysis/cascader.md §3.4）：
 * - `showSearch` 为对象时合入默认配置（`matchInputWidth: true` / `limit: 50`）；
 * - `limit <= 0` 视为 false（不限制）；
 * - 过滤只在**叶子**（或 changeOnSelect / 多选的任意层）上做；命中的结果项用
 *   `render` 产出 label（antd 薄壳会注入带高亮的 render），并挂 `SEARCH_MARK`
 *   保存完整路径（展示与回填都需要它）；
 * - `sort` 提供时覆盖默认顺序。
 */

import { type ComputedRef, computed, type Ref } from 'vue';

import {
  type BaseOptionType,
  type FieldNames,
  type FilledFieldNames,
  fillFieldNames,
  getOptionChildren,
  getOptionLabel,
  getOptionValue,
  getSearchPath,
  SEARCH_MARK,
} from '../utils';

export interface SearchConfig {
  filter?: (
    searchValue: string,
    pathOptions: BaseOptionType[],
    fieldNames: { label: string },
  ) => boolean;
  render?: (
    inputValue: string,
    pathOptions: BaseOptionType[],
    prefixCls: string,
    fieldNames: FieldNames,
  ) => unknown;
  sort?: (
    a: BaseOptionType[],
    b: BaseOptionType[],
    searchValue: string,
    fieldNames: FieldNames,
  ) => number;
  matchInputWidth?: boolean;
  limit?: number | false;
  autoClearSearchValue?: boolean;
}

/** `showSearch` → [是否开启, 配置]（上游 useSearchConfig）。 */
export function normalizeSearchConfig(
  showSearch: boolean | Omit<SearchConfig, 'render'> | undefined,
  props: { autoClearSearchValue?: boolean },
): [boolean, SearchConfig] {
  if (!showSearch) return [false, {}];

  let searchConfig: SearchConfig = {
    matchInputWidth: true,
    limit: 50,
    autoClearSearchValue: props.autoClearSearchValue,
  };
  if (showSearch && typeof showSearch === 'object') {
    const {
      filter,
      sort,
      matchInputWidth = true,
      limit = 50,
      autoClearSearchValue = props.autoClearSearchValue,
    } = showSearch;
    searchConfig = { filter, sort, matchInputWidth, limit, autoClearSearchValue };
  }
  if (typeof searchConfig.limit === 'number' && searchConfig.limit <= 0) {
    searchConfig.limit = false;
  }
  return [true, searchConfig];
}

const defaultFilter = (
  search: string,
  options: BaseOptionType[],
  { label = '' }: { label?: string },
): boolean =>
  options.some((opt) =>
    String(opt[label] ?? '')
      .toLowerCase()
      .includes(search.toLowerCase()),
  );

const defaultRender = (
  _inputValue: string,
  path: BaseOptionType[],
  _prefixCls: string,
  fieldNames: FieldNames,
): unknown => {
  const fields = fillFieldNames(fieldNames);
  const labels = path.map((option) =>
    getOptionLabel(option, fields, getOptionValue(option, fields)),
  );
  return labels.every((label) => typeof label === 'string' || typeof label === 'number')
    ? labels.join(' / ')
    : labels.flatMap((label, index) => (index ? [' / ', label] : [label]));
};

/** 搜索态的候选 options（过滤 + render + limit + sort；上游 useSearchOptions）。 */
export function computeSearchOptions(
  search: string,
  options: BaseOptionType[],
  fieldNames: FilledFieldNames,
  prefixCls: string,
  config: SearchConfig,
  enableHalfPath: boolean,
): BaseOptionType[] {
  const { filter = defaultFilter, render = defaultRender, limit = 50, sort } = config;

  const filteredOptions: BaseOptionType[] = [];
  if (!search) return [];

  function dig(
    list: BaseOptionType[],
    pathOptions: BaseOptionType[],
    parentDisabled = false,
  ): void {
    list.forEach((option) => {
      // 无 sort 且有 limit 时攒够即停（上游的 perf saving）
      if (!sort && limit !== false && limit > 0 && filteredOptions.length >= limit) return;

      const connectedPathOptions = [...pathOptions, option];
      const children = getOptionChildren(option, fieldNames);
      const mergedDisabled = parentDisabled || !!option.disabled;

      // 只在叶子（或 changeOnSelect / 多选的任意层）上做过滤
      if (!children || children.length === 0 || enableHalfPath) {
        if (filter(search, connectedPathOptions, { label: fieldNames.label })) {
          filteredOptions.push({
            ...option,
            disabled: mergedDisabled,
            [fieldNames.label]: render(search, connectedPathOptions, prefixCls, {
              label: fieldNames.label,
              value: fieldNames.value,
              children: fieldNames.children,
            }),
            [SEARCH_MARK]: connectedPathOptions,
            [fieldNames.children]: undefined,
          });
        }
      }
      if (children) {
        dig(children, connectedPathOptions, mergedDisabled);
      }
    });
  }
  dig(options, []);

  if (sort) {
    filteredOptions.sort((a, b) =>
      sort(getSearchPath(a) ?? [], getSearchPath(b) ?? [], search, {
        label: fieldNames.label,
        value: fieldNames.value,
        children: fieldNames.children,
      }),
    );
  }
  return limit !== false && limit > 0 ? filteredOptions.slice(0, limit) : filteredOptions;
}

/** 响应式包装（供组件层使用）。 */
export function useSearchOptions(
  search: Ref<string>,
  options: ComputedRef<BaseOptionType[]>,
  fieldNames: Ref<FilledFieldNames>,
  prefixCls: Ref<string>,
  config: Ref<SearchConfig>,
  enableHalfPath: boolean,
): ComputedRef<BaseOptionType[]> {
  return computed(() =>
    computeSearchOptions(
      search.value,
      options.value,
      fieldNames.value,
      prefixCls.value,
      config.value,
      enableHalfPath,
    ),
  );
}
```

### ../utils.ts

```ts
import { isVNode, type VNodeChild } from 'vue';
import { convertDataToEntities, type DataEntity } from './engine/tree';

/** Internal path keys retain both the value type and path boundaries. */
export const SHOW_PARENT = 'SHOW_PARENT';
export const SHOW_CHILD = 'SHOW_CHILD';
export type ShowCheckedStrategy = typeof SHOW_PARENT | typeof SHOW_CHILD;
export interface FieldNames {
  label?: string;
  value?: string;
  children?: string;
}
export interface FilledFieldNames {
  label: string;
  value: string;
  key: string;
  children: string;
}
export type BaseOptionType = Record<string, unknown> & {
  disabled?: boolean;
  isLeaf?: boolean;
  loading?: boolean;
};
export type DefaultOptionType = BaseOptionType & {
  label?: VNodeChild;
  value?: string | number;
  children?: DefaultOptionType[];
};
export type ValueCell = (string | number)[];
export type RawValue = string | number | ValueCell;

export function toPathKey(value: ValueCell): string {
  return JSON.stringify(value);
}
export function toPathKeys(values: ValueCell[]): string[] {
  return values.map(toPathKey);
}
export function toPathValueStr(pathKey: string): string[] {
  const value: unknown = JSON.parse(pathKey);
  if (!Array.isArray(value) || !value.every(isValue))
    throw new TypeError('[Cascader] Invalid path key');
  return value.map(String);
}
export function fillFieldNames(fieldNames?: FieldNames): FilledFieldNames {
  const { label = 'label', value = 'value', children = 'children' } = fieldNames ?? {};
  return { label, value, key: value, children };
}
export function isValue(value: unknown): value is string | number {
  return typeof value === 'string' || typeof value === 'number';
}
export function getOptionValue(option: BaseOptionType, fields: FilledFieldNames): string | number {
  const value = option[fields.value];
  if (!isValue(value))
    throw new TypeError(`[Cascader] Option ${fields.value} must be a string or number`);
  return value;
}
export function isOption(value: unknown): value is BaseOptionType {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}
export function getOptionChildren(
  option: BaseOptionType | undefined,
  fields: FilledFieldNames,
): BaseOptionType[] {
  const children = option?.[fields.children];
  if (children === undefined || children === null) return [];
  if (!Array.isArray(children) || !children.every(isOption))
    throw new TypeError(`[Cascader] Option ${fields.children} must be an array of options`);
  return children;
}
export function getSearchPath(option: BaseOptionType): BaseOptionType[] | undefined {
  const path = option[SEARCH_MARK];
  return Array.isArray(path) && path.every(isOption) ? path : undefined;
}
export function toContent(value: unknown): VNodeChild {
  if (
    value === undefined ||
    value === null ||
    typeof value === 'string' ||
    typeof value === 'number' ||
    typeof value === 'boolean' ||
    isVNode(value)
  )
    return value;
  if (Array.isArray(value)) return value.map(toContent);
  throw new TypeError('[Cascader] Option labels must be Vue renderable content');
}
export function getOptionLabel(
  option: BaseOptionType | null,
  fields: FilledFieldNames,
  fallback: string | number,
): VNodeChild {
  const label = option?.[fields.label];
  return label === undefined ? fallback : toContent(label);
}
export function isLeaf(option: BaseOptionType | undefined, fields: FilledFieldNames): boolean {
  return option?.isLeaf ?? getOptionChildren(option, fields).length === 0;
}
export function scrollIntoParentView(element: HTMLElement): void {
  const parent = element.parentElement;
  if (!parent) return;
  const offset = element.offsetTop - parent.offsetTop;
  if (offset < parent.scrollTop) parent.scrollTo({ top: offset });
  else if (offset + element.clientHeight > parent.scrollTop + parent.clientHeight)
    parent.scrollTo({ top: offset + element.clientHeight - parent.clientHeight });
}
export const SEARCH_MARK = '__rc_cascader_search_mark__';
export function getFullPathKeys(
  options: BaseOptionType[],
  fields: FilledFieldNames,
): (ValueCell | undefined)[] {
  return options.map((option) =>
    getSearchPath(option)?.map((node) => getOptionValue(node, fields)),
  );
}
function isValueCell(value: unknown): value is ValueCell {
  return Array.isArray(value) && value.every(isValue);
}
export function toRawValues(value: RawValue | RawValue[] | undefined): ValueCell[] {
  if (value === undefined) return [];
  if (isValue(value)) return [[value]];
  if (!value.length) return [];
  if (isValueCell(value)) return [value];
  return value.map((path) => {
    if (!isValueCell(path))
      throw new TypeError('[Cascader] Values must be paths of strings or numbers');
    return path;
  });
}
export function formatStrategyValues(
  pathKeys: string[],
  getEntities: () => Record<string, DataEntity>,
  strategy: ShowCheckedStrategy,
): string[] {
  const checked = new Set(pathKeys);
  const entities = getEntities();
  return pathKeys.filter((key) => {
    const entity = Object.hasOwn(entities, key) ? entities[key] : undefined;
    if (entity?.node.disabled) return true;
    return strategy === SHOW_CHILD
      ? !entity?.children?.some((child) => checked.has(child.key))
      : !(entity?.parent && !entity.parent.node.disabled && checked.has(entity.parent.key));
  });
}
export interface PathOption {
  value: string | number;
  index: number;
  option: BaseOptionType | null;
}
export function toPathOptions(
  path: ValueCell,
  options: BaseOptionType[],
  fields: FilledFieldNames,
  stringMode = false,
): PathOption[] {
  let list = options;
  return path.map((value) => {
    const index = list.findIndex((option) =>
      stringMode ? String(option[fields.value]) === String(value) : option[fields.value] === value,
    );
    const option = list[index] ?? null;
    list = getOptionChildren(option ?? undefined, fields);
    return { value: option ? getOptionValue(option, fields) : value, index, option };
  });
}
export { convertDataToEntities };
```

### ../engine/tree.ts

```ts
/**
 * Cascader 依赖的两棵「树算法」—— `@rc-component/tree` 的 Vue 版移植。
 *
 * ── 为什么在这里，而不是独立包 ──────────────────────────────────────────────
 *
 * `foundation.json` 的开放决策 `early-extract-table-core-tree-core` 结论是
 * **A：不提前抽取独立包，等第二个消费者出现**。Cascader（多选的勾选传导）是第一个
 * 消费者，所以算法先落在 `cascader/engine/`；将来 Tree 组件需要时再按
 * `ActionButton` 那套做法提升到 `_internal/`（原位置留垫片）。
 *
 * ── 两个算法 ────────────────────────────────────────────────────────────────
 *
 * 1. `convertDataToEntities(dataNodes, config)` —— 把嵌套 options 摊成扁平实体表，
 *    并补出 `parent` / `children`（实体层面）与 `level` / `pos` / `nodes`（路径）。
 * 2. `conductCheck(keyList, checked, keyEntities)` —— 勾选传导：
 *    - `checked === true`（fill）：父选中 ⇒ 向下补全所有子；子全选 ⇒ 向上补父；
 *      部分选中 ⇒ 父记 halfChecked。
 *    - `checked === { checked: false, halfCheckedKeys }`（clean）：反向清理。
 *
 * 契约来源：`@rc-component/tree@1.x` 的 `es/utils/treeUtil.js`（convertDataToEntities /
 * traverseDataNodes）与 `es/utils/conductUtil.js`（conductCheck / fill+clean）。
 * 行为逐条对齐，**不复制源码**。
 */

/** 树节点实体。 */
export interface DataEntity {
  /** 原始节点。 */
  node: Record<string, unknown>;
  /** 从根到当前节点的原始节点链（Cascader 用它拼 pathKey）。 */
  nodes: Record<string, unknown>[];
  /** 在同级中的下标。 */
  index: number;
  /** 节点 key（`getKey(key, pos)`：key 缺失时回退 pos）。 */
  key: string;
  /** 位置串（形如 `0-1-2`）。 */
  pos: string;
  /** 层级（根为 0）。 */
  level: number;
  /** 父实体（根为 undefined）。 */
  parent?: DataEntity;
  /** 子实体列表（构造期填充）。 */
  children?: DataEntity[];
}

export interface Wrapper {
  posEntities: Record<string, DataEntity>;
  keyEntities: Record<string, DataEntity>;
  [key: string]: unknown;
}

export interface ConvertConfig {
  /** 用自定义字段解析（Cascader 传 `{ key: value字段, children }`）。 */
  fieldNames?: { key?: string; children?: string };
  /** 包装器扩展（Cascader 用它挂 `pathKeyEntities`）。 */
  initWrapper?: (wrapper: Wrapper) => Wrapper | undefined;
  /** 每个实体构造后的钩子（Cascader 用它把 key 覆写成 pathKey）。 */
  processEntity?: (entity: DataEntity, wrapper: Wrapper) => void;
  /** 全部处理完的钩子。 */
  onProcessFinished?: (wrapper: Wrapper) => void;
}

const DEFAULT_FIELD_NAMES = { key: 'key', children: 'children' };

function getPosition(level: string | number, index: number): string {
  return `${level}-${index}`;
}

function getKey(key: unknown, pos: string): string {
  return key !== null && key !== undefined ? String(key) : pos;
}

/**
 * 遍历嵌套数据（广度优先按层级展开，与上游同序）。
 *
 * ⚠️ 上游 `traverseDataNodes` 的 `nodes` 是**路径链**（根→当前），不是 children ——
 *    Cascader 的 typed value path 依赖完整的 nodes 路径。
 */
export function traverseDataNodes(
  dataNodes: Record<string, unknown>[],
  callback: (item: {
    node: Record<string, unknown>;
    index: number;
    pos: string;
    key: string;
    parentPos: string;
    level: number;
    nodes: Record<string, unknown>[];
  }) => void,
  config: ConvertConfig = {},
): void {
  const { key: fieldKey, children: fieldChildren } = {
    ...DEFAULT_FIELD_NAMES,
    ...(config.fieldNames ?? {}),
  };

  /**
   * @param level 本节点的 level；根调用传 **0** ⇒ 第一层节点的 level 为 0
   *              （rc-tree 的 level 从 0 起算）。⚠️ 不能用 `parentLevel + 1`
   *              的写法——虚拟根会把 -1 加成 0 再传给子，整体偏移一层。
   */
  function processNode(
    node: Record<string, unknown> | null,
    index: number,
    parent: { pos: string; level: number } | null,
    pathNodes: Record<string, unknown>[],
    level: number,
  ): void {
    const mergedParent = parent as { pos: string; level: number } | undefined;
    const children = (node ? node[fieldChildren] : dataNodes) as
      | Record<string, unknown>[]
      | undefined;
    // biome-ignore lint/style/noNonNullAssertion: node 非空时 mergedParent 必由调用方给出（pos/parentPos 都从它派生）
    const pos = node ? getPosition(mergedParent!.pos, index) : '0';
    const connectNodes = node ? [...pathNodes, node] : [];

    if (node) {
      callback({
        node,
        index,
        pos,
        key: getKey(node[fieldKey], pos),
        // biome-ignore lint/style/noNonNullAssertion: 同上 —— 这一支只在 node 非空时执行
        parentPos: mergedParent!.pos,
        level,
        nodes: connectNodes,
      });
    }

    (children ?? []).forEach((child, childIndex) => {
      processNode(child, childIndex, { pos, level }, connectNodes, level + 1);
    });
  }

  // ⚠️ 虚拟根的 level 是 **-1**：递归里 `level + 1` 后第一层节点的 level 才是 0
  //    （rc-tree 的 level 从 0 起算；传 0 会让整棵树偏移一层，conduct 的层级分组全错）
  processNode(null, 0, { pos: '0', level: -1 }, [], -1);
}

/**
 * 摊平嵌套数据为实体表。
 *
 * 与上游同构：同时产出 `posEntities` 与 `keyEntities`，`initWrapper` 可扩展包装器，
 * `processEntity` 在每个实体建好后回调（Cascader 借此把 `entity.key` 覆写成 pathKey）。
 */
export function convertDataToEntities(
  dataNodes: Record<string, unknown>[],
  config: ConvertConfig = {},
): Wrapper {
  const posEntities: Record<string, DataEntity> = {};
  const keyEntities: Record<string, DataEntity> = {};
  let wrapper: Wrapper = { posEntities, keyEntities };
  if (config.initWrapper) {
    wrapper = config.initWrapper(wrapper) ?? wrapper;
  }

  traverseDataNodes(
    dataNodes,
    (item) => {
      const { node, index, pos, key, parentPos, level, nodes } = item;
      const entity: DataEntity = { node, nodes, index, key, pos, level };
      const mergedKey = getKey(key, pos);

      Object.defineProperty(posEntities, pos, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });
      Object.defineProperty(keyEntities, mergedKey, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });

      entity.parent = Object.hasOwn(posEntities, parentPos) ? posEntities[parentPos] : undefined;
      if (entity.parent) {
        entity.parent.children = entity.parent.children || [];
        entity.parent.children.push(entity);
      }

      config.processEntity?.(entity, wrapper);
    },
    config,
  );

  config.onProcessFinished?.(wrapper);
  return wrapper;
}

// ================================ conduct ================================

export interface ConductResult {
  checkedKeys: string[];
  halfCheckedKeys: string[];
}

/** 上游 `isCheckDisabled`：`disabled` / `disableCheckbox` / `checkable === false`。 */
function isCheckDisabled(node: Record<string, unknown> | undefined): boolean {
  if (!node) return false;
  const { disabled, disableCheckbox, checkable } = node as {
    disabled?: boolean;
    disableCheckbox?: boolean;
    checkable?: boolean;
  };
  return !!(disabled || disableCheckbox) || checkable === false;
}

function removeFromCheckedKeys(
  halfCheckedKeys: Set<string>,
  checkedKeys: Set<string>,
): Set<string> {
  const filtered = new Set<string>();
  halfCheckedKeys.forEach((key) => {
    if (!checkedKeys.has(key)) filtered.add(key);
  });
  return filtered;
}

/** 按层级分组（上游 `conductCheck` 的第一步）。 */
function groupByLevel(keyEntities: Record<string, DataEntity>) {
  const levelEntities = new Map<number, Set<DataEntity>>();
  let maxLevel = 0;
  Object.keys(keyEntities).forEach((key) => {
    // noUncheckedIndexedAccess：索引访问可能 undefined（key 来自 Object.keys，防御式收窄）
    const entity = Object.hasOwn(keyEntities, key) ? keyEntities[key] : undefined;
    if (!entity) return;
    const { level } = entity;
    // ⚠️ 用局部变量接住（`get(...)!` 消不掉，且 `Map.get` 的返回类型永远是 `T | undefined`）
    let levelSet = levelEntities.get(level);
    if (!levelSet) {
      levelSet = new Set();
      levelEntities.set(level, levelSet);
    }
    levelSet.add(entity);
    maxLevel = Math.max(maxLevel, level);
  });
  return { levelEntities, maxLevel };
}

/** 自底向上：父的全部（非禁用）子是否都选中 / 部分选中。 */
function conductParent(
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  checkedKeys: Set<string>,
  halfCheckedKeys: Set<string>,
  getDisabled: (node: Record<string, unknown>) => boolean,
  onAllChecked: (parentKey: string) => void,
  onPartialChecked: (parentKey: string) => void,
): void {
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { node } = entity;
      const parent = entity.parent;
      if (!parent || getDisabled(node) || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const checked = checkedKeys.has(key);
          if (allChecked && !checked) allChecked = false;
          if (!partialChecked && (checked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (allChecked) onAllChecked(parent.key);
      if (partialChecked) onPartialChecked(parent.key);
      visitedKeys.add(parent.key);
    });
  }
}

function fillConductCheck(
  keys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  const halfCheckedKeys = new Set<string>();

  // 自顶向下：父选中 ⇒ 补子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (checkedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.add(childEntity.key);
          });
      }
    });
  }

  // 自底向上：子全选 ⇒ 补父；部分 ⇒ half
  conductParent(
    levelEntities,
    maxLevel,
    checkedKeys,
    halfCheckedKeys,
    getDisabled,
    (parentKey) => checkedKeys.add(parentKey),
    (parentKey) => halfCheckedKeys.add(parentKey),
  );

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

function cleanConductCheck(
  keys: Set<string>,
  halfKeys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  let halfCheckedKeys = new Set(halfKeys);

  // 自顶向下：未选中且非半选 ⇒ 清掉子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (!checkedKeys.has(key) && !halfCheckedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.delete(childEntity.key);
          });
      }
    });
  }

  // ⚠️ 自底向上必须**单遍**：`delete(parent.key)` 会立刻影响更高一层的判定
  //    （上游就是同一轮里先算 allChecked / partialChecked 再改 checkedKeys）。
  //    拆成两遍会让高层读到「本该删掉的父」，half 集合偏大。
  halfCheckedKeys = new Set<string>();
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { parent, node } = entity;
      if (getDisabled(node) || !parent || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const isChecked = checkedKeys.has(key);
          if (allChecked && !isChecked) allChecked = false;
          if (!partialChecked && (isChecked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (!allChecked) checkedKeys.delete(parent.key);
      if (partialChecked) halfCheckedKeys.add(parent.key);
      visitedKeys.add(parent.key);
    });
  }

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

/**
 * 勾选传导。
 *
 * @param keyList 当前 key 列表
 * @param checked `true` = fill（补全）；`{ checked: false, halfCheckedKeys }` = clean（清理）
 * @param keyEntities `convertDataToEntities` 产出的 `keyEntities`
 */
export function conductCheck(
  keyList: string[],
  checked: true | { checked: false; halfCheckedKeys: string[] },
  keyEntities: Record<string, DataEntity>,
  getCheckDisabled?: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const getDisabled = getCheckDisabled ?? isCheckDisabled;

  // 只处理存在的 key（上游会 warning 缺失的 key，本仓静默过滤）
  const keys = new Set(keyList.filter((key) => Object.hasOwn(keyEntities, key)));

  const { levelEntities, maxLevel } = groupByLevel(keyEntities);

  if (checked === true) {
    return fillConductCheck(keys, levelEntities, maxLevel, getDisabled);
  }
  return cleanConductCheck(
    keys,
    new Set(checked.halfCheckedKeys),
    levelEntities,
    maxLevel,
    getDisabled,
  );
}
```

## 后缀图标 (suffix)

通过 `suffixIcon` 替换默认箭头；下拉框可切换笑脸、定位与火箭三种本地图标，触发器的行为保持不变。

### suffix.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 suffix demo：suffixIcon 可替换默认箭头
import { EnvironmentOutlined, RocketOutlined, SmileOutlined } from '@apollo-design/icons';
import { Cascader, Select, Tag } from '@apollo-design/ui';
import { type Component, computed, h, ref } from 'vue';

type IconMode = 'smile' | 'environment' | 'rocket';

const iconMode = ref<IconMode>('smile');

const iconOptions: { value: IconMode; label: string }[] = [
  { value: 'smile', label: 'Smile' },
  { value: 'environment', label: 'Environment' },
  { value: 'rocket', label: 'Rocket' },
];

const iconMap: Record<IconMode, Component> = {
  smile: SmileOutlined,
  environment: EnvironmentOutlined,
  rocket: RocketOutlined,
};

const suffixIcon = computed(() =>
  h(iconMap[iconMode.value], { style: { color: '#fa8c16', fontSize: '16px' } }),
);

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

function onIconChange(value: unknown): void {
  iconMode.value = value as IconMode;
}
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 16px">
      <span>后缀图标</span>
      <Select
        aria-label="后缀图标"
        :value="iconMode"
        :options="iconOptions"
        style="width: 140px"
        @change="onIconChange"
      />
      <Tag color="orange">{{ iconMode }}</Tag>
    </div>

    <Cascader :options="options" :suffix-icon="suffixIcon" placeholder="请选择地区" />

    <p style="margin-bottom: 0">`suffixIcon` 会替换默认的下拉箭头，不会影响浮层展开。</p>
  </div>
</template>
```

## 变体 (variant)

`variant` 支持 `outlined`、`borderless` 与 `filled` 三种输入框形态；通过下拉框切换后可以观察边框与背景的即时变化。

### variant.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 variant demo：outlined / borderless / filled
import { Cascader, Select, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

type Variant = 'outlined' | 'borderless' | 'filled';

const variant = ref<Variant>('outlined');

const variantOptions: { value: Variant; label: string }[] = [
  { value: 'outlined', label: 'outlined' },
  { value: 'borderless', label: 'borderless' },
  { value: 'filled', label: 'filled' },
];

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

function onVariantChange(value: unknown): void {
  variant.value = value as Variant;
}
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 16px">
      <span>输入框变体</span>
      <Select
        aria-label="输入框变体"
        :value="variant"
        :options="variantOptions"
        style="width: 150px"
        @change="onVariantChange"
      />
      <Tag color="blue">{{ variant }}</Tag>
    </div>

    <Cascader :variant="variant" :options="options" placeholder="请选择地区" />

    <p style="margin-bottom: 0">切换选择器样式：描边、无边框或填充背景。</p>
  </div>
</template>
```

## 悬停展开 (hover)

`expandTrigger` 控制子级列的展开方式：`hover` 在指针移入父级选项时展开，`click` 则需要点击；下拉框可随时切换两种模式。

### hover.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 hover demo：expandTrigger 控制展开方式
import { Cascader, Select, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

type ExpandTrigger = 'click' | 'hover';

const expandTrigger = ref<ExpandTrigger>('hover');

const triggerOptions: { value: ExpandTrigger; label: string }[] = [
  { value: 'click', label: '点击展开' },
  { value: 'hover', label: '悬停展开' },
];

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

function onTriggerChange(value: unknown): void {
  expandTrigger.value = value as ExpandTrigger;
}
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 16px">
      <span>展开方式</span>
      <Select
        aria-label="展开触发方式"
        :value="expandTrigger"
        :options="triggerOptions"
        style="width: 150px"
        @change="onTriggerChange"
      />
      <Tag color="blue">
        {{ expandTrigger === 'hover' ? '鼠标移入列项即展开' : '点击列项展开' }}
      </Tag>
    </div>

    <Cascader :expand-trigger="expandTrigger" :options="options" placeholder="请选择地区" />

    <p style="margin-bottom: 0">
      `expandTrigger="hover"` 时指针悬停父级选项会展开下一列；切换为 `click` 后需要点击展开。
    </p>
  </div>
</template>
```

## 自定义面板 (render-panel)

`#popupRender="{ menu }"` 接收级联面板 VNode，以 `<component :is="menu" />` 渲染，并在其外层插入自定义头部与底部：头部显示面板标题，底部展示当前选择并提供清空按钮。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 render-panel demo：popupRender 包装整个级联面板
import { Button, Cascader, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';
import type { CascaderOutputValue } from '../interface';

const value = ref<CascaderOutputValue>([]);

const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京' }],
  },
];

const labels: Record<string, string> = {
  zhejiang: '浙江',
  hangzhou: '杭州',
  ningbo: '宁波',
  jiangsu: '江苏',
  nanjing: '南京',
};

const display = computed(() =>
  value.value.length
    ? value.value.map((item) => labels[String(item)] ?? item).join(' / ')
    : '尚未选择',
);
</script>

<template>
  <div>
    <Cascader
      v-model:value="value"
      :options="options"
      placeholder="打开面板查看自定义包装层"
    >
      <template #popupRender="{ menu }">
        <div class="cascader-render-panel">
          <div class="cascader-render-panel-header">
            <strong>区域选择面板</strong><span>popupRender 自定义包装层</span>
          </div>
          <component :is="menu" />
          <div class="cascader-render-panel-footer">
            <span>当前：{{ display }}</span>
            <Button size="small" type="link" :disabled="!value.length" @click="value = []">清空选择</Button>
          </div>
        </div>
      </template>
    </Cascader>

    <div style="margin-top: 16px">
      <Tag color="blue">当前选择</Tag>
      <span>{{ display }}</span>
    </div>

    <p style="margin-bottom: 0">
      面板顶部与底部由 `popupRender` 注入，底部按钮可以直接清空当前选择。
    </p>
  </div>
</template>

<style>
.cascader-render-panel {
  width: 320px;
  max-width: calc(100vw - 32px);
  background: var(--apollo-color-bg-elevated);
  color: var(--apollo-color-text);
}

.cascader-render-panel-header {
  display: flex;
  flex-wrap: wrap;
  align-items: baseline;
  justify-content: space-between;
  gap: 12px;
  padding: 10px 12px;
  border-bottom: 1px solid var(--apollo-color-border-secondary);
}

.cascader-render-panel-header span {
  color: var(--apollo-color-text-tertiary);
  font-size: 12px;
}

.cascader-render-panel-footer {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  padding: 8px 12px;
  border-top: 1px solid var(--apollo-color-border-secondary);
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

### ../interface.ts

```ts
import type { CSSProperties, VNode, VNodeChild } from 'vue';
import type { SemanticInput } from '../_internal/use-merge-semantic';
import type { SizeType } from '../config-provider/size-context';
import type { SelectCommonPlacement, SelectSlots, SelectVariant } from '../select/interface';
import type { SearchConfig } from './hooks/search';
import type { BaseOptionType, FieldNames, RawValue, ShowCheckedStrategy, ValueCell } from './utils';

export type CascaderValue = RawValue | ValueCell[];
export type CascaderOutputValue = ValueCell | ValueCell[];
export type CascaderSelectedOptions = (BaseOptionType | null)[] | (BaseOptionType | null)[][];
export type CascaderSearchConfig = Omit<SearchConfig, 'render' | 'searchValue' | 'onSearch'>;
export interface CascaderSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: { root?: string; list?: string; listItem?: string };
}
export interface CascaderSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: { root?: CSSProperties; list?: CSSProperties; listItem?: CSSProperties };
}
export interface CascaderPanelProps {
  prefixCls?: string;
  options?: BaseOptionType[];
  value?: CascaderValue;
  defaultValue?: CascaderValue;
  multiple?: boolean;
  fieldNames?: FieldNames;
  changeOnSelect?: boolean;
  showCheckedStrategy?: ShowCheckedStrategy;
  loadData?: (selectedOptions: BaseOptionType[]) => void | Promise<void>;
  expandTrigger?: 'click' | 'hover';
  expandIcon?: VNodeChild;
  loadingIcon?: VNodeChild;
  direction?: 'ltr' | 'rtl';
  notFoundContent?: VNodeChild;
  disabled?: boolean;
  popupMenuColumnStyle?: CSSProperties;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderPanelProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderPanelProps>;
  'onUpdate:value'?: (value: CascaderOutputValue) => void;
  onChange?: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
}
export interface CascaderProps extends Omit<CascaderPanelProps, 'classNames' | 'styles'> {
  id?: string;
  checkable?: boolean;
  size?: SizeType;
  loading?: boolean;
  variant?: SelectVariant;
  bordered?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild };
  clearIcon?: VNodeChild;
  removeIcon?: VNodeChild;
  suffixIcon?: VNodeChild;
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  showSearch?: boolean | CascaderSearchConfig;
  searchValue?: string;
  autoClearSearchValue?: boolean;
  placeholder?: VNodeChild;
  popupClassName?: string;
  dropdownClassName?: string;
  popupStyle?: CSSProperties;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement;
  status?: 'error' | 'warning';
  maxTagCount?: number;
  maxTagTextLength?: number;
  maxTagPlaceholder?: VNodeChild;
  classNames?: SemanticInput<CascaderSemanticClassNames, CascaderProps>;
  styles?: SemanticInput<CascaderSemanticStyles, CascaderProps>;
  'onUpdate:open'?: (open: boolean) => void;
  'onUpdate:searchValue'?: (value: string) => void;
  onOpenChange?: (open: boolean) => void;
  onSearch?: (value: string) => void;
  onFocus?: (event: FocusEvent) => void;
  onBlur?: (event: FocusEvent) => void;
  onClear?: () => void;
  onPopupScroll?: (event: Event) => void;
  onKeydown?: (event: KeyboardEvent) => void;
  onKeyup?: (event: KeyboardEvent) => void;
  onMousedown?: (event: MouseEvent) => void;
}
export interface CascaderEmits {
  'update:value': (value: CascaderOutputValue) => void;
  change: (value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions) => void;
  'update:open': (open: boolean) => void;
  openChange: (open: boolean) => void;
  'update:searchValue': (value: string) => void;
  search: (value: string) => void;
  focus: (event: FocusEvent) => void;
  blur: (event: FocusEvent) => void;
  clear: () => void;
  popupScroll: (event: Event) => void;
  keydown: (event: KeyboardEvent) => void;
  keyup: (event: KeyboardEvent) => void;
  mousedown: (event: MouseEvent) => void;
}
export interface CascaderOptionSlots {
  optionRender?: (scope: { option: BaseOptionType; pathOptions: BaseOptionType[] }) => VNodeChild;
  searchRender?: (scope: {
    inputValue: string;
    pathOptions: BaseOptionType[];
    fieldNames: FieldNames;
  }) => VNodeChild;
  expandIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
  loadingIcon?: (scope: { option: BaseOptionType }) => VNodeChild;
}
export interface CascaderPanelSlots extends CascaderOptionSlots {
  notFoundContent?: () => VNodeChild;
}
export interface CascaderSlots extends CascaderPanelSlots {
  default?: () => VNodeChild;
  placeholder?: () => VNodeChild;
  displayRender?: (scope: {
    labels: VNodeChild[];
    selectedOptions: (BaseOptionType | null)[];
  }) => VNodeChild;
  suffixIcon?: SelectSlots['suffixIcon'];
  searchIcon?: SelectSlots['suffixIcon'];
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  maxTagPlaceholder?: (scope: {
    omittedValues: { value: ValueCell; label: VNodeChild; disabled?: boolean }[];
  }) => VNodeChild;
  popupRender?: (scope: { menu: VNode }) => VNodeChild;
}
export interface CascaderRef {
  readonly nativeElement: HTMLElement | null;
  focus: (options?: FocusOptions) => void;
  blur: () => void;
}
```

### ../../_internal/use-merge-semantic.ts

````ts
/**
 * 语义化 `classNames` / `styles` 的合并。
 *
 * 契约来源：antd 6.6.4 的 `es/_util/hooks/useMergeSemantic/index.js`（**逐条对齐**）。
 *
 * 为什么单独抽出来：72 个组件里有 60 多个都有 `classNames` / `styles`，合并语义
 * 一旦不一致，就会出现「Button 的覆盖优先级和 Empty 不一样」这类只有用户才会发现的问题。
 * 所以合并规则集中在这里，组件只声明「合并哪些来源、按什么顺序」。
 *
 * ── 与 antd 的对应关系（合并顺序是契约，不能改）────────────────────────────────
 *
 * ```
 * // antd（Empty）
 * const [mergedClassNames, mergedStyles] = useMergeSemantic(
 *   [contextClassNames, classNames],                          // classNamesList
 *   [contextStyles, contextStyleRoot, styles, styleRoot],     // stylesList
 *   { props },
 * );
 * ```
 *
 * 其中 `contextStyleRoot = useSemanticRootStyle(contextStyle)`、`styleRoot = useSemanticRootStyle(style)`，
 * 即把 `style` 这个平铺的 prop 包成 `{ root: style }` 再进合并。
 *
 * 三条必须逐字保留的判据：
 *   1. **classNames 是「拼接」不是「覆盖」** —— `clsx(acc[key], curVal)`，同名键会连起来。
 *   2. **styles 是「逐键浅合并、后者胜」** —— 与 classNames 不同，这里不是拼接。
 *   3. **`style` prop 排在 `styles.root` 之后** —— 所以 `style` 会**覆盖** `styles.root`。
 *      这条最反直觉，也最容易被「顺手改成更合理的顺序」。
 *
 * ── 函数式变体（裁决 `empty-semantic-fn` = B：支持）───────────────────────────
 *
 * antd 允许传 `(info: { props }) => 对象`。我们在 `resolveSemantic` 里逐字对应：
 * 判据是 `isFunction(value) ? value(info) : value`，**没有**额外的「只在需要时求值」优化
 * —— 那种优化会让函数式与对象式的行为出现差异。
 *
 * ── `schema`（嵌套语义槽）—— **2026-10-03 补齐** ──────────────────────────────
 *
 * antd 的第四参 `schema` 用 `_default` 把「字符串形态的嵌套键」落到指定子槽
 * （`classNames.popup = 'x'` ≡ `classNames.popup = { root: 'x' }`），并在最后用
 * `fillObjectBySchema` 保证嵌套键**恒为对象**。
 *
 * 本仓此前没有它，用「只要有一侧是对象就递归」绕过 —— 那在**字符串与对象混用**时
 * 会产垃圾键（`Object.keys('x')`）。antd 6.6.4 里 **9 个组件**传了 schema
 * （`select` / `cascader` / `color-picker` / `menu` / `tabs` / `image` / `splitter` /
 * `input.Search` / `table`），Table 是第一个**真的需要**它的（`body.cell` / `header.cell`）。
 *
 * ⚠️ **两条语义并存、不能合并**：不给 schema 时保持本仓既有行为（7 个消费者钉住它），
 *    给了 schema 才走 antd 的 `mergeClassNamesBySchema`。
 *    判据见 `__tests__/use-merge-semantic.test.ts` 的「反向哨兵」那一条。
 *
 * ── 这个模块没有证明什么 ──────────────────────────────────────────────────────
 *   - 没证明各组件的**合并顺序声明**是对的。本模块只保证「给定顺序，合并结果正确」；
 *     顺序本身由各组件的 compat 用例与 antd 对照（Empty 见 `__tests__/semantic.test.ts`）。
 *   - 没证明**所有该传 schema 的组件都传了**。schema 档 2026-10-03 实现，
 *     select / cascader / color-picker / tabs / image（×2）/ splitter 已补第四参；
 *     menu 无语义通道、`input.Search` 未实现（见 `docs/KNOWN-ISSUES.md` §2 留痕）。
 *
 *   ⚠️ 无 schema 的宽松路径（`mergeClassNames`）**仍在服务既有消费者**：它在
 *     「字符串 + 对象混用」时会产垃圾键（`Object.keys('x')`）。这条**曾**登记在
 *     `docs/KNOWN-ISSUES.md`，该文件的 §1 已于 2026-10-07 清零、登记项转入 §2 的
 *     「已修 / 已裁决」；但宽松路径本身**未改**（7 个既有消费者的用例钉住它）。
 *     若将来统一到 schema 档，需同步改这 7 处并重跑它们的 L4/L6。
 */

import { isFunction } from '@apollo-design/utils';
import {
  type ComputedRef,
  type CSSProperties,
  computed,
  type MaybeRefOrGetter,
  toValue,
} from 'vue';

/** 函数式语义化拿到的上下文。与 antd 的 `{ props }` 同构。 */
export interface SemanticInfo<P> {
  props: P;
}

/** 对象式或函数式的语义化输入。 */
export type SemanticInput<T, P> = T | ((info: SemanticInfo<P>) => T | undefined);

/** 任意可响应化的输入。普通值、ref、getter 都接受（与 `toValue` 同构）。 */
export type MaybeSource<T> = MaybeRefOrGetter<T>;

/**
 * ⚠️ **刻意不用** `_internal/clsx.ts` 那一份（2026-10-07 核对过）。
 *
 * 这里是**更窄**的语义：只保留字符串，数字 / 数组 / 对象一律丢弃。
 * 而共享层那份会展开数组与对象（`{a:true}` → `'a'`）。语义化 `classNames` 的槽位值
 * 本来就是字符串，宽版本在这里只会把「传错了形态」静默变成一个类名。
 * ⇒ 别为了「消重」把它换成共享版 —— 那份窄语义是有意的。
 */
function clsx(...values: unknown[]): string {
  return values.filter((v) => typeof v === 'string' && v !== '').join(' ');
}

/**
 * 求值一个语义化输入。
 *
 * 与 antd 的 `resolveStyleOrClass(value, info)` 逐字对应 —— 包括
 * **只在 `isFunction` 时求值**这一点：传 `null` / `undefined` 会原样返回，
 * 由下游的 `filter(Boolean)` 丢掉。
 */
export function resolveSemantic<T, P>(
  value: SemanticInput<T, P> | undefined | null,
  info: SemanticInfo<P>,
): T | undefined {
  if (value === undefined || value === null) return undefined;
  return isFunction(value) ? (value as (i: SemanticInfo<P>) => T | undefined)(info) : value;
}

/**
 * 合并 classNames。**拼接**语义：同名键连起来，不覆盖。
 *
 * 与 antd 的 `mergeClassNames(schema, ...classNames)` 在 `schema === undefined` 时等价。
 *
 * ⚠️ 实现里有一次类型断言（`as Record<string, string | undefined>`）。
 *    它**不是**类型漏洞，而是「语义键集合由调用方的泛型决定」这一事实的必然结果：
 *    函数体只做键的遍历与字符串拼接，不认识任何具体键。用 `as any` 才是漏洞，
 *    这里断言到的是精确的中间形态。
 */
export function mergeClassNames<CN extends object>(
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const cur = record[key];
      const prev = acc[key];
      // 嵌套语义对象（如 Select 的 classNames.popup.{root,list,listItem}）递归合并；
      // 叶子值按 clsx 拼接（select 期 AutoComplete 抓出：浅合并在 popup 上丢数据）
      if (isPlainRecord(cur) || isPlainRecord(prev)) {
        acc[key] = mergeClassNames((prev ?? {}) as never, (cur ?? {}) as never);
      } else {
        acc[key] = clsx(prev as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

function isPlainRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// ---------------------------------------------------------------------------
// schema（嵌套语义槽）—— antd `useMergeSemantic` 的第四参
// ---------------------------------------------------------------------------

/**
 * schema 的**键名首字符**集合。
 *
 * 与 antd 的 `ValidChar`（`_util/type.ts:91`）**逐字相同**：**只有小写 a–z**。
 * 这不是「随便写的」—— 它正是让 `_default`（下划线开头）**不落进**索引签名、
 * 从而不与 `{ _default?: string }` 冲突的机制。
 * ⇒ 别「顺手」把大写或下划线加进来（会让 `SemanticSchema` 立刻变成 `never` 交叉）。
 */
type LowerChar =
  | 'a'
  | 'b'
  | 'c'
  | 'd'
  | 'e'
  | 'f'
  | 'g'
  | 'h'
  | 'i'
  | 'j'
  | 'k'
  | 'l'
  | 'm'
  | 'n'
  | 'o'
  | 'p'
  | 'q'
  | 'r'
  | 's'
  | 't'
  | 'u'
  | 'v'
  | 'w'
  | 'x'
  | 'y'
  | 'z';

/**
 * 嵌套语义槽的映射表。与 antd 的 `SemanticSchema` 同构。
 *
 * `_default: 'root'` 的语义（**逐条来自 antd 的 `mergeClassNames`**）：
 *   - 该键收到**普通对象** ⇒ 递归按子 schema 合并；
 *   - 该键收到**非对象**（字符串）⇒ 落到 `acc[key][_default]`（即 `classNames.popup = 'x'`
 *     ≡ `classNames.popup = { root: 'x' }`）；
 *   - **没有** `_default` 的子 schema（如 `image` 的 `placeholder: {}`）⇒ 只保证该键
 *     恒为对象（`fillObjectBySchema` 的 `||= {}`），不做字符串转换。
 */
export type SemanticSchema = { _default?: string } & {
  [key: `${LowerChar}${string}`]: SemanticSchema;
};

/**
 * 按**任意字符串键**读子 schema。
 *
 * ⚠️ 必须走这层 cast：`SemanticSchema` 的索引签名是 `` `${LowerChar}${string}` ``
 *    （antd 的 `ValidChar` 口径，见上面的注释），而 `Object.keys()` 给的是 `string`
 *    ⇒ 直接写 `schema[key]` 会 **TS7053**。这里的 cast 是**诚实的**：运行时 schema 的键
 *    本来就来自调用方写的对象字面量，`Object.keys` 拿到的正是那些键。
 */
function subSchema(schema: SemanticSchema, key: string): SemanticSchema | undefined {
  return (schema as Record<string, SemanticSchema | undefined>)[key];
}

/**
 * 按 schema 补齐对象结构（antd `fillObjectBySchema` 逐字）。
 *
 * 两条判据：
 *   ① `_default` 键 ⇒ `newObj[key] ||= {}`（保证**至少是空对象**，不会残留 `undefined`）；
 *   ② 其余子 schema ⇒ 递归（空 schema `{}` 会让该键变成 `{}`）。
 */
export function fillObjectBySchema(
  obj: Record<string, unknown> | undefined,
  schema: SemanticSchema,
): Record<string, unknown> {
  const newObj: Record<string, unknown> = { ...(obj ?? {}) };
  for (const key of Object.keys(schema)) {
    if (subSchema(schema, key)?._default) {
      newObj[key] ||= {};
    } else {
      newObj[key] = fillObjectBySchema(
        newObj[key] as Record<string, unknown> | undefined,
        subSchema(schema, key) as SemanticSchema,
      );
    }
  }
  return newObj;
}

/**
 * **带 schema** 的 classNames 合并（antd `mergeClassNames(schema, ...classNames)` 逐字）。
 *
 * ⚠️ 与下面**无 schema** 的 `mergeClassNames` 是**两条不同的语义**，不要合并：
 *    - 无 schema：只要有一侧是对象就**递归**（本仓在 select/auto-complete 期加的行为，
 *      比 antd 更宽松，且已被 7 个组件的既有用例钉住）；
 *    - 有 schema：**只有 schema 声明过的键**才特殊处理，其余键一律 `clsx` 平铺（antd 语义）。
 *
 *    两者的差别在「字符串 vs 对象混用」时可见：
 *      `classNames: { popup: 'x' }` 与 `{ popup: { root: 'y' } }` 两个来源
 *      —— schema 版给 `popup.root = 'x y'`（正确）；无 schema 版会把 `'x'` 当对象递归
 *      （`Object.keys('x')` ⇒ 垃圾键）。这正是 antd 需要 `_default` 的原因。
 */
export function mergeClassNamesBySchema<CN extends object>(
  schema: SemanticSchema,
  ...sources: readonly (Partial<CN> | undefined)[]
): Partial<CN> {
  const acc: Record<string, unknown> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, unknown>;
    for (const key of Object.keys(record)) {
      const keySchema = subSchema(schema, key);
      const cur = record[key];
      if (keySchema) {
        if (isPlainRecord(cur)) {
          acc[key] = mergeClassNamesBySchema(keySchema, (acc[key] ?? {}) as never, cur as never);
        } else {
          const defaultField = keySchema._default;
          if (defaultField) {
            const target = (acc[key] ?? {}) as Record<string, unknown>;
            target[defaultField] = clsx(
              target[defaultField] as string | undefined,
              cur as string | undefined,
            );
            acc[key] = target;
          }
        }
      } else {
        acc[key] = clsx(acc[key] as string | undefined, cur as string | undefined);
      }
    }
  }
  return acc as Partial<CN>;
}

/**
 * 合并 styles。**逐键浅合并、后者胜** —— 注意与 classNames 的语义不同。
 *
 * 与 antd 的 `mergeStyles(...styles)` 等价。断言理由同 `mergeClassNames`。
 */
export function mergeStyles<ST extends object>(
  ...sources: readonly (Partial<ST> | undefined)[]
): Partial<ST> {
  const acc: Record<string, CSSProperties | undefined> = {};
  for (const source of sources) {
    if (!source) continue;
    const record = source as Record<string, CSSProperties | string | undefined>;
    for (const key of Object.keys(record)) {
      // 🚨 **叶子可能是 CSS 字符串**（Vue 的 `style` attr 允许字符串，而 `attrs.style`
      //    会经 `semanticRootStyle` 进到这里）。直接展开字符串会得到
      //    `{ 0: 'w', 1: 'i', … }` ⇒ Vue 的 `setStyle` 抛
      //    `'set' on proxy: trap returned falsish for property '0'`。
      acc[key] = { ...acc[key], ...normalizeStyleValue(record[key]) };
    }
  }
  return acc as Partial<ST>;
}

/**
 * `'width: 240px; color: red'` → `{ width: '240px', color: 'red' }`。
 *
 * ⚠️ 不引入 `@vue/shared` 的 `parseStringStyle`：它是 `vue` 的**传递依赖**，
 *    直接 import 属于幻影依赖（R7 的精神）。这里只需要支持 `;` 分隔的声明段，
 *    与 Vue 自己的实现判据一致（空段 / 无冒号的段跳过）。
 */
function parseStyleString(text: string): CSSProperties {
  const out: Record<string, string> = {};
  for (const part of text.split(';')) {
    const index = part.indexOf(':');
    if (index < 0) continue;
    const name = part.slice(0, index).trim();
    if (!name) continue;
    out[name] = part.slice(index + 1).trim();
  }
  return out as CSSProperties;
}

/** 样式叶子归一：字符串解析成对象，其余原样。 */
function normalizeStyleValue(value: CSSProperties | string | undefined): CSSProperties | undefined {
  if (typeof value === 'string') {
    return parseStyleString(value);
  }
  return value;
}

/**
 * 把平铺的 `style` 包成 `{ root: style }`。
 *
 * 与 antd 的 `useSemanticRootStyle(style, key = 'root')` 等价 —— 包括
 * 「`style` 为空时返回 `undefined` 而不是 `{ root: undefined }`」这一点：
 * 后者会让 `mergeStyles` 多产出一个 `root` 键，进而在 DOM 上多出一个空的 `style=""`。
 */
export function semanticRootStyle(
  style: CSSProperties | string | undefined,
  key = 'root',
): Record<string, CSSProperties> | undefined {
  if (!style) {
    return undefined;
  }
  // 🚨 `style` 可能是 **CSS 字符串**（`<Input style="width: 240px" />` —— Vue 的 `style`
  //    attr 两种形态都合法）。必须在这里解析成对象，否则下游 `mergeStyles` 的
  //    对象展开会把它拆成 `{ 0: 'w', … }`（Issue #7.1 实测）。
  return { [key]: typeof style === 'string' ? parseStyleString(style) : style };
}

/**
 * 把「可能为空的样式」转成可以直接 `v-bind` 的属性对象。
 *
 * 空样式返回 `{}`（**连 `style` 这个键都没有**），非空返回 `{ style }`。
 *
 * ── 为什么必须做这一步（2026-09-18，empty 实测）──────────────────────────────
 *
 * `mergeStyles()` 的返回值**恒**是对象（可能是 `{}`）。直接绑 `:style` 时：
 *
 * | 渲染路径 | 结果 |
 * |---|---|
 * | 客户端 | `patchStyle` 会把空样式移除 —— 没有 `style` 属性 ✓ |
 * | **SSR** | `ssrRenderAttrs` 对 `style` 键是**无条件**输出的 ⇒ 渲染出 `style=""` ✗ |
 *
 * React（antd）在样式为空时**不输出该属性**。所以 SSR 产物会与上游有差异，
 * 而且每个元素多 9 字节 —— 72 个组件 × 多层结构累积起来是可观的体积。
 *
 * 实测：Empty 一层就有 3 个元素带 `style=""`；改成 `v-bind="styleAttrs(x)"` 后归零。
 *
 * ⚠️ 这个差异 L4 **测不出来** —— 投影会把「没有 style 属性」与 `style=""`
 *    都归一化成空串（`(node.style ?? []).join(';')` 两边都是 `''`）。
 *    它是被渲染 SSR 预览页时肉眼发现的，所以既有 L1 断言也有这里。
 *
 * ⚠️ 所有用 `useMergeSemantic` 的组件都应该这样绑样式，而不是 `:style="mergedStyles.x"`。
 */
export function styleAttrs(style: CSSProperties | undefined): { style?: CSSProperties } {
  if (!style) return {};
  const record = style as Record<string, unknown>;
  for (const key of Object.keys(record)) {
    if (record[key] !== undefined) return { style };
  }
  return {};
}

export interface UseMergeSemanticResult<CN extends object, ST extends object> {
  classNames: ComputedRef<Partial<CN>>;
  styles: ComputedRef<Partial<ST>>;
}

/**
 * 响应式版本的 `useMergeSemantic`。
 *
 * 与 antd 的差别只有一处、且是平台差异（PLATFORM）：antd 每次渲染都重跑一遍合并，
 * 我们用 `computed` 缓存 —— 语义相同，但**依赖必须可追踪**，所以来源要用
 * `() => value` 的形式传，而不是先取值再传。
 *
 * @param classNamesSources 按优先级从低到高排列（后者拼接在前者之后）
 * @param stylesSources 按优先级从低到高排列（后者覆盖前者）
 * @param props 传给函数式变体的 `info.props`。**可以是 getter / ref** ——
 *   函数式变体每次重算都要看到**当前** props。传 `mergedProps.value` 那种
 *   setup 期快照会让 `disabled` / `size` / `variant` 变化后函数式仍按旧值计算
 *   （Issue #3.2）。裸对象仍然可用（`toValue` 原样返回）。
 * @param schema **嵌套语义槽**的映射表（antd 第四参）。给了它就会：
 *   ① classNames 走 `mergeClassNamesBySchema`（`_default` 的字符串→对象转换）；
 *   ② 两个结果都过一遍 `fillObjectBySchema`（保证嵌套键恒为对象）。
 *   ⚠️ 不给时**保持本仓既有行为**（无 schema 的递归合并）—— 7 个既有消费者不受影响。
 */
export function useMergeSemantic<P extends object, CN extends object, ST extends object>(
  classNamesSources: readonly MaybeSource<SemanticInput<Partial<CN>, P> | undefined>[],
  stylesSources: readonly MaybeSource<SemanticInput<Partial<ST>, P> | undefined>[],
  props: MaybeRefOrGetter<P>,
  schema?: SemanticSchema,
): UseMergeSemanticResult<CN, ST> {
  // ⚠️ `info` 必须在**每次重算时**新建，且 `props` 要在 computed 内 `toValue` ——
  //    在 setup 期建一次会把首帧的 props 快照焊死（Issue #3.2）。
  const classNames = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = classNamesSources.map((source) =>
      resolveSemantic<Partial<CN>, P>(toValue(source), info),
    );
    const merged = schema
      ? mergeClassNamesBySchema<CN>(schema, ...resolved)
      : mergeClassNames<CN>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<CN>;
  });

  const styles = computed(() => {
    const info: SemanticInfo<P> = { props: toValue(props) };
    const resolved = stylesSources.map((source) =>
      resolveSemantic<Partial<ST>, P>(toValue(source), info),
    );
    const merged = mergeStyles<ST>(...resolved);
    return (schema ? fillObjectBySchema(merged as never, schema) : merged) as Partial<ST>;
  });

  return { classNames, styles };
}
````

### ../../config-provider/size-context.ts

````ts
/**
 * `SizeContext` —— 组件尺寸。
 *
 * 契约来源：antd 6.6.4 的 `es/config-provider/SizeContext.tsx` + `hooks/useSize.ts`。
 *
 * ── 为什么它是**独立 context** 而不是 ConfigContext 的一个字段 ──────────────────
 *
 * antd 把它拆出去是为了「`componentSize` 变化时只重渲染读尺寸的组件」。
 * 本项目的理由更硬：`ConfigContextValue` 是**一个**响应式对象，任何字段变化都会
 * 触发所有读它的 `computed` 重算；而尺寸是被最多组件读的字段之一，独立出来能明显
 * 收窄依赖面。形态上也与 antd 对齐（便于迁移）。
 */

import { type ComputedRef, computed, type InjectionKey, inject } from 'vue';

/**
 * 尺寸。
 *
 * ⚠️ `'medium'` 与 `'middle'` **两个都要**：antd 6 起 `'medium'` 是推荐写法，
 * `'middle'` 仍是默认值且未移除（上游注释：`middle is deprecated and will be removed
 * in v7`）。`COMPONENT-RULES.md` §4 要求枚举值与 antd 一致 ⇒ 不裁剪成 `'medium'`。
 */
export type SizeType = 'small' | 'medium' | 'middle' | 'large';

/**
 * 注入键。
 *
 * 值是 `ComputedRef` 而不是裸值 —— 这样 `useSize` 在 `computed` 里读 `.value`
 * 会被追踪，`componentSize` 变化能传导到下游（对齐 antd 的 context 更新）。
 */
export const sizeContextKey: InjectionKey<ComputedRef<SizeType | undefined>> =
  Symbol('apolloSizeContext');

/**
 * 读取组件尺寸，与自己的 prop 合并。与 antd 的 `useSize` 逐字对应。
 *
 * 四条判据（逐条来自 `hooks/useSize.ts`）：
 *   1. `!customSize` ⇒ 用 context（⚠️ 真值判据：`0` / `''` 也走这一支）。
 *   2. `customSize` 是字符串 ⇒ `customSize ?? size`（字符串恒真，等价于直接返回）。
 *   3. `customSize` 是函数 ⇒ `customSize(size)`。
 *   4. 其余（数字 / 对象）⇒ 用 context。
 *
 * @example
 * ```ts
 * const mergedSize = useSize(props.size);   // ComputedRef<SizeType | undefined>
 * ```
 */
export function useSize<T extends string | number | undefined | object>(
  customSize?: T | ((ctxSize: SizeType | undefined) => T),
): ComputedRef<T | SizeType | undefined> {
  const injected = inject(sizeContextKey, undefined);

  return computed(() => {
    const ctxSize = injected?.value;

    if (!customSize) return ctxSize;

    if (typeof customSize === 'string') return customSize ?? ctxSize;

    if (typeof customSize === 'function') {
      return (customSize as (ctxSize: SizeType | undefined) => T)(ctxSize);
    }

    return ctxSize;
  });
}
````

### ../../select/interface.ts

```ts
/** Public Vue contracts for Select and its option data. */

import type { CSSProperties, VNodeChild } from 'vue';
import type { SizeType } from '../config-provider/size-context';

// ---------------------------------------------------------------------------
// 基础值类型
// ---------------------------------------------------------------------------

export type RawValueType = string | number;

/** antd 的 `SelectValue`。 */
export type SelectValue =
  | RawValueType
  | RawValueType[]
  | LabeledValue
  | LabeledValue[]
  | null
  | undefined;

/** antd 的 `LabeledValue`（labelInValue 的输出形态）。 */
export interface LabeledValue {
  key?: RawValueType;
  value: RawValueType;
  label?: unknown;
}

/** rc 的内部形态（`labelInValue` 的中间表示）。 */
export interface LabelInValueType {
  label?: unknown;
  value: RawValueType;
  key?: RawValueType;
  disabled?: boolean;
  title?: string;
}

export interface BaseOptionType {
  disabled?: boolean;
  className?: string;
  style?: CSSProperties;
  title?: string;
  [name: string]: unknown;
}

export interface DefaultOptionType extends BaseOptionType {
  label?: unknown;
  value?: RawValueType | null;
  children?: Omit<DefaultOptionType, 'children'>[];
  options?: DefaultOptionType[];
}

export type SelectOptionType = BaseOptionType | DefaultOptionType;

/** antd `OptionProps`（`Select.Option` / `Select.OptGroup`，deprecated 但保留）。 */
export interface OptionProps extends BaseOptionType {
  value?: RawValueType | null;
  children?: unknown;
}

export interface OptGroupProps extends BaseOptionType {
  label?: unknown;
  children?: unknown;
}

// ---------------------------------------------------------------------------
// 模式 / 尺寸 / 状态
// ---------------------------------------------------------------------------

/**
 * 公开模式只有 `multiple` / `tags` —— antd 把 `mode="combobox"` 吞成单选
 * （`index.tsx` 的 `mode` memo），只有 `SECRET_COMBOBOX_MODE_DO_NOT_USE` 才真走
 * combobox（AutoComplete 用）。内核实现 combobox 分支，公开类型不声明。
 */
export type SelectMode = 'multiple' | 'tags';

/** 内核模式（engine 内部用）。 */
export type InternalSelectMode = SelectMode | 'combobox';

/**
 * 尺寸。**直接别名到 `config-provider` 的 `SizeType`**（`'small' | 'medium' | 'middle' | 'large'`）。
 *
 * 上游 `SelectProps.size` 就是 `SizeType`；此前手抄成 `'small' | 'middle' | 'large'`
 * 漏了 `medium`（运行时 `useSize` 是吃 `SizeType` 的 ⇒ 类型比运行时窄，Issue #4.3）。
 */
export type SelectSize = SizeType;

export type SelectVariant = 'outlined' | 'borderless' | 'filled' | 'underlined';

export type SelectStatus = 'error' | 'warning' | 'success' | 'validating';

/** antd `SelectCommonPlacement`（`_util/motion.ts` 的 4 值）。 */
export type SelectCommonPlacement = 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight';

export type SelectDirection = 'ltr' | 'rtl';

// ---------------------------------------------------------------------------
// 搜索配置
// ---------------------------------------------------------------------------

export type FilterFunc<OptionType> = (inputValue: string, option: OptionType) => boolean;

export interface SearchConfig<OptionType = DefaultOptionType> {
  autoClearSearchValue?: boolean;
  filterOption?: boolean | FilterFunc<OptionType>;
  filterSort?: (optionA: OptionType, optionB: OptionType, info: { searchValue: string }) => number;
  optionFilterProp?: string | string[];
}

export type SelectSearchConfig = SearchConfig<DefaultOptionType>;

// ---------------------------------------------------------------------------
// 语义槽（classNames / styles）
// ---------------------------------------------------------------------------

export interface SelectSemanticClassNames {
  root?: string;
  prefix?: string;
  suffix?: string;
  input?: string;
  placeholder?: string;
  content?: string;
  item?: string;
  itemContent?: string;
  itemRemove?: string;
  clear?: string;
  popup?: {
    root?: string;
    listItem?: string;
    list?: string;
  };
}

export interface SelectSemanticStyles {
  root?: CSSProperties;
  prefix?: CSSProperties;
  suffix?: CSSProperties;
  input?: CSSProperties;
  placeholder?: CSSProperties;
  content?: CSSProperties;
  item?: CSSProperties;
  itemContent?: CSSProperties;
  itemRemove?: CSSProperties;
  clear?: CSSProperties;
  popup?: {
    root?: CSSProperties;
    listItem?: CSSProperties;
    list?: CSSProperties;
  };
}

export interface FieldNames {
  value?: string;
  label?: string;
  groupLabel?: string;
  options?: string;
}

// ---------------------------------------------------------------------------
// Engine content function types; public component content uses slots.
// ---------------------------------------------------------------------------

/** `FlattenOptionData`（rc `interface.d.ts`）。 */
export interface FlattenOptionData<OptionType = DefaultOptionType> {
  label?: unknown;
  data: OptionType;
  key: string | number;
  value?: RawValueType;
  groupOption?: boolean;
  group?: boolean;
}

/** 选择器里一个已选值的展示形态（rc `DisplayValueType`）。 */
export interface DisplayValueType {
  key?: string | number;
  value?: RawValueType;
  label?: unknown;
  title?: unknown;
  disabled?: boolean;
  index?: number;
}

/** `tagRender` 的入参（rc `CustomTagProps`）。 */
export interface CustomTagProps {
  label?: unknown;
  value?: RawValueType;
  disabled: boolean;
  onClose: (event?: MouseEvent) => void;
  closable: boolean;
  isMaxTag: boolean;
  index?: number;
}

export type OptionRenderFn = (
  option: FlattenOptionData<DefaultOptionType>,
  info: { index: number },
) => VNodeChild;

export type LabelRenderFn = (props: LabelInValueType) => VNodeChild;

export type TagRenderFn = (props: CustomTagProps) => VNodeChild;

export type PopupRenderFn = (menu: unknown) => VNodeChild;

export type ScrollToArg =
  | number
  | {
      index?: number;
      align?: 'top' | 'bottom' | 'auto';
      key?: string | number;
    };

// ---------------------------------------------------------------------------
// 实例句柄（antd `RefSelectProps` = rc `BaseSelectRef`）
// ---------------------------------------------------------------------------

export interface SelectRef {
  focus: (options?: FocusOptions) => void;
  blur: () => void;
  scrollTo: (arg?: ScrollToArg) => void;
  nativeElement: HTMLElement | null;
}

// ---------------------------------------------------------------------------
// Props
// ---------------------------------------------------------------------------

export interface SelectProps<ValueType = SelectValue> {
  // ---- 身份 ----
  id?: string;
  prefixCls?: string;
  /** ⚠️ Vue 原生 `class` / `style` 走 attrs（不是 prop）；这里只为类型面留位。 */
  class?: unknown;

  // ---- 值 ----
  value?: ValueType;
  defaultValue?: ValueType;
  /** 输出 `{ label, value }` 而非裸值。 */
  labelInValue?: boolean;
  /** 回填值取 option 的哪个字段（默认 `label`）。 */
  optionLabelProp?: string;
  fieldNames?: FieldNames;

  // ---- 模式 ----
  mode?: SelectMode;

  // ---- 选项 ----
  options?: DefaultOptionType[];
  /** 搜索时列表的最大高度（默认 256）。 */
  listHeight?: number;
  /** 虚拟滚动的估算行高（默认 controlHeight = 32）。 */
  listItemHeight?: number;
  virtual?: boolean;
  /** 键盘上下键是否自动激活第一项（默认 true，combobox 为 false）。 */
  defaultActiveFirstOption?: boolean;
  // ---- 搜索 ----
  showSearch?: boolean | SelectSearchConfig;
  /** Search text; supports v-model:searchValue. */
  searchValue?: string;
  /** @deprecated 用 `showSearch.autoClearSearchValue` */
  autoClearSearchValue?: boolean;
  /** @deprecated 用 `showSearch.filterOption` */
  filterOption?: boolean | FilterFunc<DefaultOptionType>;
  /** @deprecated 用 `showSearch.filterSort` */
  filterSort?: SearchConfig<DefaultOptionType>['filterSort'];
  /** @deprecated 用 `showSearch.optionFilterProp` */
  optionFilterProp?: string | string[];

  // ---- 外观 ----
  size?: SelectSize;
  variant?: SelectVariant;
  /** @deprecated 用 `variant` */
  bordered?: boolean;
  status?: SelectStatus;
  disabled?: boolean;
  loading?: boolean;
  placeholder?: string;
  /** @deprecated 默认显示箭头，隐藏请用空的 `#suffixIcon` 插槽或 `showArrow: false` */
  showArrow?: boolean;
  allowClear?: boolean | { clearIcon?: VNodeChild; label?: string };
  maxLength?: number;

  // ---- 多选 ----
  maxCount?: number;
  maxTagCount?: number;
  maxTagTextLength?: number;
  tokenSeparators?: string[] | ((input: string) => string[]);

  // ---- 浮层 ----
  open?: boolean;
  defaultOpen?: boolean;
  placement?: SelectCommonPlacement;
  direction?: SelectDirection;
  popupMatchSelectWidth?: boolean | number;
  getPopupContainer?: (node: HTMLElement) => HTMLElement | ShadowRoot;
  transitionName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  popupClassName?: string;
  /** @deprecated 用 `classNames.popup.root` */
  dropdownClassName?: string;
  /** @deprecated 用 `styles.popup.root` */
  dropdownStyle?: CSSProperties;
  popupStyle?: CSSProperties;

  // ---- 语义槽 ----
  classNames?: SelectSemanticClassNames;
  styles?: SelectSemanticStyles;

  // ---- 无障碍 ----
  tabIndex?: number;
  autoFocus?: boolean;
  title?: string;
  role?: string;
}

// ---------------------------------------------------------------------------
// 事件（Vue 侧：语义事件 + v-model 同发，见 PITFALLS 162）
// ---------------------------------------------------------------------------

export interface SelectEmits<ValueType = SelectValue> {
  change: [value: ValueType, option: DefaultOptionType | DefaultOptionType[] | undefined];
  'update:value': [value: ValueType];
  select: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  deselect: [value: RawValueType | LabeledValue, option: DefaultOptionType];
  search: [value: string];
  'update:searchValue': [value: string];
  openChange: [open: boolean];
  'update:open': [open: boolean];
  focus: [event: FocusEvent];
  blur: [event: FocusEvent];
  clear: [];
  popupScroll: [event: Event];
  inputKeyDown: [event: KeyboardEvent];
}

// ---------------------------------------------------------------------------
// Slots（规则 C8-R2：ReactNode / render prop 一律 slot —— **不**保留同名 prop。
// 文本类 prop（placeholder）保留 string 便捷形态，slot 优先。）
// ---------------------------------------------------------------------------

export interface SelectSlots {
  default?: () => VNodeChild;
  prefix?: () => VNodeChild;
  suffixIcon?: (props: {
    searchValue: string;
    open: boolean;
    focused: boolean;
    showSearch: boolean;
    loading?: boolean;
  }) => VNodeChild;
  searchIcon?: () => VNodeChild;
  loadingIcon?: () => VNodeChild;
  clearIcon?: () => VNodeChild;
  removeIcon?: () => VNodeChild;
  menuItemSelectedIcon?: (props: {
    value?: unknown;
    disabled?: boolean;
    isSelected?: boolean;
  }) => VNodeChild;
  placeholder?: () => VNodeChild;
  notFoundContent?: () => VNodeChild;
  optionRender?: (props: {
    option: FlattenOptionData<DefaultOptionType>;
    index: number;
  }) => VNodeChild;
  tagRender?: (props: CustomTagProps) => VNodeChild;
  labelRender?: (props: LabelInValueType) => VNodeChild;
  popupRender?: (props: { menu: VNodeChild }) => VNodeChild;
  maxTagPlaceholder?: (props: { omittedValues: DisplayValueType[] }) => VNodeChild;
}
```

### ../hooks/search.ts

```ts
/**
 * Cascader 的搜索 hooks —— `useSearchConfig` / `useSearchOptions` 的 Vue 版。
 *
 * 判据（docs/analysis/cascader.md §3.4）：
 * - `showSearch` 为对象时合入默认配置（`matchInputWidth: true` / `limit: 50`）；
 * - `limit <= 0` 视为 false（不限制）；
 * - 过滤只在**叶子**（或 changeOnSelect / 多选的任意层）上做；命中的结果项用
 *   `render` 产出 label（antd 薄壳会注入带高亮的 render），并挂 `SEARCH_MARK`
 *   保存完整路径（展示与回填都需要它）；
 * - `sort` 提供时覆盖默认顺序。
 */

import { type ComputedRef, computed, type Ref } from 'vue';

import {
  type BaseOptionType,
  type FieldNames,
  type FilledFieldNames,
  fillFieldNames,
  getOptionChildren,
  getOptionLabel,
  getOptionValue,
  getSearchPath,
  SEARCH_MARK,
} from '../utils';

export interface SearchConfig {
  filter?: (
    searchValue: string,
    pathOptions: BaseOptionType[],
    fieldNames: { label: string },
  ) => boolean;
  render?: (
    inputValue: string,
    pathOptions: BaseOptionType[],
    prefixCls: string,
    fieldNames: FieldNames,
  ) => unknown;
  sort?: (
    a: BaseOptionType[],
    b: BaseOptionType[],
    searchValue: string,
    fieldNames: FieldNames,
  ) => number;
  matchInputWidth?: boolean;
  limit?: number | false;
  autoClearSearchValue?: boolean;
}

/** `showSearch` → [是否开启, 配置]（上游 useSearchConfig）。 */
export function normalizeSearchConfig(
  showSearch: boolean | Omit<SearchConfig, 'render'> | undefined,
  props: { autoClearSearchValue?: boolean },
): [boolean, SearchConfig] {
  if (!showSearch) return [false, {}];

  let searchConfig: SearchConfig = {
    matchInputWidth: true,
    limit: 50,
    autoClearSearchValue: props.autoClearSearchValue,
  };
  if (showSearch && typeof showSearch === 'object') {
    const {
      filter,
      sort,
      matchInputWidth = true,
      limit = 50,
      autoClearSearchValue = props.autoClearSearchValue,
    } = showSearch;
    searchConfig = { filter, sort, matchInputWidth, limit, autoClearSearchValue };
  }
  if (typeof searchConfig.limit === 'number' && searchConfig.limit <= 0) {
    searchConfig.limit = false;
  }
  return [true, searchConfig];
}

const defaultFilter = (
  search: string,
  options: BaseOptionType[],
  { label = '' }: { label?: string },
): boolean =>
  options.some((opt) =>
    String(opt[label] ?? '')
      .toLowerCase()
      .includes(search.toLowerCase()),
  );

const defaultRender = (
  _inputValue: string,
  path: BaseOptionType[],
  _prefixCls: string,
  fieldNames: FieldNames,
): unknown => {
  const fields = fillFieldNames(fieldNames);
  const labels = path.map((option) =>
    getOptionLabel(option, fields, getOptionValue(option, fields)),
  );
  return labels.every((label) => typeof label === 'string' || typeof label === 'number')
    ? labels.join(' / ')
    : labels.flatMap((label, index) => (index ? [' / ', label] : [label]));
};

/** 搜索态的候选 options（过滤 + render + limit + sort；上游 useSearchOptions）。 */
export function computeSearchOptions(
  search: string,
  options: BaseOptionType[],
  fieldNames: FilledFieldNames,
  prefixCls: string,
  config: SearchConfig,
  enableHalfPath: boolean,
): BaseOptionType[] {
  const { filter = defaultFilter, render = defaultRender, limit = 50, sort } = config;

  const filteredOptions: BaseOptionType[] = [];
  if (!search) return [];

  function dig(
    list: BaseOptionType[],
    pathOptions: BaseOptionType[],
    parentDisabled = false,
  ): void {
    list.forEach((option) => {
      // 无 sort 且有 limit 时攒够即停（上游的 perf saving）
      if (!sort && limit !== false && limit > 0 && filteredOptions.length >= limit) return;

      const connectedPathOptions = [...pathOptions, option];
      const children = getOptionChildren(option, fieldNames);
      const mergedDisabled = parentDisabled || !!option.disabled;

      // 只在叶子（或 changeOnSelect / 多选的任意层）上做过滤
      if (!children || children.length === 0 || enableHalfPath) {
        if (filter(search, connectedPathOptions, { label: fieldNames.label })) {
          filteredOptions.push({
            ...option,
            disabled: mergedDisabled,
            [fieldNames.label]: render(search, connectedPathOptions, prefixCls, {
              label: fieldNames.label,
              value: fieldNames.value,
              children: fieldNames.children,
            }),
            [SEARCH_MARK]: connectedPathOptions,
            [fieldNames.children]: undefined,
          });
        }
      }
      if (children) {
        dig(children, connectedPathOptions, mergedDisabled);
      }
    });
  }
  dig(options, []);

  if (sort) {
    filteredOptions.sort((a, b) =>
      sort(getSearchPath(a) ?? [], getSearchPath(b) ?? [], search, {
        label: fieldNames.label,
        value: fieldNames.value,
        children: fieldNames.children,
      }),
    );
  }
  return limit !== false && limit > 0 ? filteredOptions.slice(0, limit) : filteredOptions;
}

/** 响应式包装（供组件层使用）。 */
export function useSearchOptions(
  search: Ref<string>,
  options: ComputedRef<BaseOptionType[]>,
  fieldNames: Ref<FilledFieldNames>,
  prefixCls: Ref<string>,
  config: Ref<SearchConfig>,
  enableHalfPath: boolean,
): ComputedRef<BaseOptionType[]> {
  return computed(() =>
    computeSearchOptions(
      search.value,
      options.value,
      fieldNames.value,
      prefixCls.value,
      config.value,
      enableHalfPath,
    ),
  );
}
```

### ../utils.ts

```ts
import { isVNode, type VNodeChild } from 'vue';
import { convertDataToEntities, type DataEntity } from './engine/tree';

/** Internal path keys retain both the value type and path boundaries. */
export const SHOW_PARENT = 'SHOW_PARENT';
export const SHOW_CHILD = 'SHOW_CHILD';
export type ShowCheckedStrategy = typeof SHOW_PARENT | typeof SHOW_CHILD;
export interface FieldNames {
  label?: string;
  value?: string;
  children?: string;
}
export interface FilledFieldNames {
  label: string;
  value: string;
  key: string;
  children: string;
}
export type BaseOptionType = Record<string, unknown> & {
  disabled?: boolean;
  isLeaf?: boolean;
  loading?: boolean;
};
export type DefaultOptionType = BaseOptionType & {
  label?: VNodeChild;
  value?: string | number;
  children?: DefaultOptionType[];
};
export type ValueCell = (string | number)[];
export type RawValue = string | number | ValueCell;

export function toPathKey(value: ValueCell): string {
  return JSON.stringify(value);
}
export function toPathKeys(values: ValueCell[]): string[] {
  return values.map(toPathKey);
}
export function toPathValueStr(pathKey: string): string[] {
  const value: unknown = JSON.parse(pathKey);
  if (!Array.isArray(value) || !value.every(isValue))
    throw new TypeError('[Cascader] Invalid path key');
  return value.map(String);
}
export function fillFieldNames(fieldNames?: FieldNames): FilledFieldNames {
  const { label = 'label', value = 'value', children = 'children' } = fieldNames ?? {};
  return { label, value, key: value, children };
}
export function isValue(value: unknown): value is string | number {
  return typeof value === 'string' || typeof value === 'number';
}
export function getOptionValue(option: BaseOptionType, fields: FilledFieldNames): string | number {
  const value = option[fields.value];
  if (!isValue(value))
    throw new TypeError(`[Cascader] Option ${fields.value} must be a string or number`);
  return value;
}
export function isOption(value: unknown): value is BaseOptionType {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}
export function getOptionChildren(
  option: BaseOptionType | undefined,
  fields: FilledFieldNames,
): BaseOptionType[] {
  const children = option?.[fields.children];
  if (children === undefined || children === null) return [];
  if (!Array.isArray(children) || !children.every(isOption))
    throw new TypeError(`[Cascader] Option ${fields.children} must be an array of options`);
  return children;
}
export function getSearchPath(option: BaseOptionType): BaseOptionType[] | undefined {
  const path = option[SEARCH_MARK];
  return Array.isArray(path) && path.every(isOption) ? path : undefined;
}
export function toContent(value: unknown): VNodeChild {
  if (
    value === undefined ||
    value === null ||
    typeof value === 'string' ||
    typeof value === 'number' ||
    typeof value === 'boolean' ||
    isVNode(value)
  )
    return value;
  if (Array.isArray(value)) return value.map(toContent);
  throw new TypeError('[Cascader] Option labels must be Vue renderable content');
}
export function getOptionLabel(
  option: BaseOptionType | null,
  fields: FilledFieldNames,
  fallback: string | number,
): VNodeChild {
  const label = option?.[fields.label];
  return label === undefined ? fallback : toContent(label);
}
export function isLeaf(option: BaseOptionType | undefined, fields: FilledFieldNames): boolean {
  return option?.isLeaf ?? getOptionChildren(option, fields).length === 0;
}
export function scrollIntoParentView(element: HTMLElement): void {
  const parent = element.parentElement;
  if (!parent) return;
  const offset = element.offsetTop - parent.offsetTop;
  if (offset < parent.scrollTop) parent.scrollTo({ top: offset });
  else if (offset + element.clientHeight > parent.scrollTop + parent.clientHeight)
    parent.scrollTo({ top: offset + element.clientHeight - parent.clientHeight });
}
export const SEARCH_MARK = '__rc_cascader_search_mark__';
export function getFullPathKeys(
  options: BaseOptionType[],
  fields: FilledFieldNames,
): (ValueCell | undefined)[] {
  return options.map((option) =>
    getSearchPath(option)?.map((node) => getOptionValue(node, fields)),
  );
}
function isValueCell(value: unknown): value is ValueCell {
  return Array.isArray(value) && value.every(isValue);
}
export function toRawValues(value: RawValue | RawValue[] | undefined): ValueCell[] {
  if (value === undefined) return [];
  if (isValue(value)) return [[value]];
  if (!value.length) return [];
  if (isValueCell(value)) return [value];
  return value.map((path) => {
    if (!isValueCell(path))
      throw new TypeError('[Cascader] Values must be paths of strings or numbers');
    return path;
  });
}
export function formatStrategyValues(
  pathKeys: string[],
  getEntities: () => Record<string, DataEntity>,
  strategy: ShowCheckedStrategy,
): string[] {
  const checked = new Set(pathKeys);
  const entities = getEntities();
  return pathKeys.filter((key) => {
    const entity = Object.hasOwn(entities, key) ? entities[key] : undefined;
    if (entity?.node.disabled) return true;
    return strategy === SHOW_CHILD
      ? !entity?.children?.some((child) => checked.has(child.key))
      : !(entity?.parent && !entity.parent.node.disabled && checked.has(entity.parent.key));
  });
}
export interface PathOption {
  value: string | number;
  index: number;
  option: BaseOptionType | null;
}
export function toPathOptions(
  path: ValueCell,
  options: BaseOptionType[],
  fields: FilledFieldNames,
  stringMode = false,
): PathOption[] {
  let list = options;
  return path.map((value) => {
    const index = list.findIndex((option) =>
      stringMode ? String(option[fields.value]) === String(value) : option[fields.value] === value,
    );
    const option = list[index] ?? null;
    list = getOptionChildren(option ?? undefined, fields);
    return { value: option ? getOptionValue(option, fields) : value, index, option };
  });
}
export { convertDataToEntities };
```

### ../engine/tree.ts

```ts
/**
 * Cascader 依赖的两棵「树算法」—— `@rc-component/tree` 的 Vue 版移植。
 *
 * ── 为什么在这里，而不是独立包 ──────────────────────────────────────────────
 *
 * `foundation.json` 的开放决策 `early-extract-table-core-tree-core` 结论是
 * **A：不提前抽取独立包，等第二个消费者出现**。Cascader（多选的勾选传导）是第一个
 * 消费者，所以算法先落在 `cascader/engine/`；将来 Tree 组件需要时再按
 * `ActionButton` 那套做法提升到 `_internal/`（原位置留垫片）。
 *
 * ── 两个算法 ────────────────────────────────────────────────────────────────
 *
 * 1. `convertDataToEntities(dataNodes, config)` —— 把嵌套 options 摊成扁平实体表，
 *    并补出 `parent` / `children`（实体层面）与 `level` / `pos` / `nodes`（路径）。
 * 2. `conductCheck(keyList, checked, keyEntities)` —— 勾选传导：
 *    - `checked === true`（fill）：父选中 ⇒ 向下补全所有子；子全选 ⇒ 向上补父；
 *      部分选中 ⇒ 父记 halfChecked。
 *    - `checked === { checked: false, halfCheckedKeys }`（clean）：反向清理。
 *
 * 契约来源：`@rc-component/tree@1.x` 的 `es/utils/treeUtil.js`（convertDataToEntities /
 * traverseDataNodes）与 `es/utils/conductUtil.js`（conductCheck / fill+clean）。
 * 行为逐条对齐，**不复制源码**。
 */

/** 树节点实体。 */
export interface DataEntity {
  /** 原始节点。 */
  node: Record<string, unknown>;
  /** 从根到当前节点的原始节点链（Cascader 用它拼 pathKey）。 */
  nodes: Record<string, unknown>[];
  /** 在同级中的下标。 */
  index: number;
  /** 节点 key（`getKey(key, pos)`：key 缺失时回退 pos）。 */
  key: string;
  /** 位置串（形如 `0-1-2`）。 */
  pos: string;
  /** 层级（根为 0）。 */
  level: number;
  /** 父实体（根为 undefined）。 */
  parent?: DataEntity;
  /** 子实体列表（构造期填充）。 */
  children?: DataEntity[];
}

export interface Wrapper {
  posEntities: Record<string, DataEntity>;
  keyEntities: Record<string, DataEntity>;
  [key: string]: unknown;
}

export interface ConvertConfig {
  /** 用自定义字段解析（Cascader 传 `{ key: value字段, children }`）。 */
  fieldNames?: { key?: string; children?: string };
  /** 包装器扩展（Cascader 用它挂 `pathKeyEntities`）。 */
  initWrapper?: (wrapper: Wrapper) => Wrapper | undefined;
  /** 每个实体构造后的钩子（Cascader 用它把 key 覆写成 pathKey）。 */
  processEntity?: (entity: DataEntity, wrapper: Wrapper) => void;
  /** 全部处理完的钩子。 */
  onProcessFinished?: (wrapper: Wrapper) => void;
}

const DEFAULT_FIELD_NAMES = { key: 'key', children: 'children' };

function getPosition(level: string | number, index: number): string {
  return `${level}-${index}`;
}

function getKey(key: unknown, pos: string): string {
  return key !== null && key !== undefined ? String(key) : pos;
}

/**
 * 遍历嵌套数据（广度优先按层级展开，与上游同序）。
 *
 * ⚠️ 上游 `traverseDataNodes` 的 `nodes` 是**路径链**（根→当前），不是 children ——
 *    Cascader 的 typed value path 依赖完整的 nodes 路径。
 */
export function traverseDataNodes(
  dataNodes: Record<string, unknown>[],
  callback: (item: {
    node: Record<string, unknown>;
    index: number;
    pos: string;
    key: string;
    parentPos: string;
    level: number;
    nodes: Record<string, unknown>[];
  }) => void,
  config: ConvertConfig = {},
): void {
  const { key: fieldKey, children: fieldChildren } = {
    ...DEFAULT_FIELD_NAMES,
    ...(config.fieldNames ?? {}),
  };

  /**
   * @param level 本节点的 level；根调用传 **0** ⇒ 第一层节点的 level 为 0
   *              （rc-tree 的 level 从 0 起算）。⚠️ 不能用 `parentLevel + 1`
   *              的写法——虚拟根会把 -1 加成 0 再传给子，整体偏移一层。
   */
  function processNode(
    node: Record<string, unknown> | null,
    index: number,
    parent: { pos: string; level: number } | null,
    pathNodes: Record<string, unknown>[],
    level: number,
  ): void {
    const mergedParent = parent as { pos: string; level: number } | undefined;
    const children = (node ? node[fieldChildren] : dataNodes) as
      | Record<string, unknown>[]
      | undefined;
    // biome-ignore lint/style/noNonNullAssertion: node 非空时 mergedParent 必由调用方给出（pos/parentPos 都从它派生）
    const pos = node ? getPosition(mergedParent!.pos, index) : '0';
    const connectNodes = node ? [...pathNodes, node] : [];

    if (node) {
      callback({
        node,
        index,
        pos,
        key: getKey(node[fieldKey], pos),
        // biome-ignore lint/style/noNonNullAssertion: 同上 —— 这一支只在 node 非空时执行
        parentPos: mergedParent!.pos,
        level,
        nodes: connectNodes,
      });
    }

    (children ?? []).forEach((child, childIndex) => {
      processNode(child, childIndex, { pos, level }, connectNodes, level + 1);
    });
  }

  // ⚠️ 虚拟根的 level 是 **-1**：递归里 `level + 1` 后第一层节点的 level 才是 0
  //    （rc-tree 的 level 从 0 起算；传 0 会让整棵树偏移一层，conduct 的层级分组全错）
  processNode(null, 0, { pos: '0', level: -1 }, [], -1);
}

/**
 * 摊平嵌套数据为实体表。
 *
 * 与上游同构：同时产出 `posEntities` 与 `keyEntities`，`initWrapper` 可扩展包装器，
 * `processEntity` 在每个实体建好后回调（Cascader 借此把 `entity.key` 覆写成 pathKey）。
 */
export function convertDataToEntities(
  dataNodes: Record<string, unknown>[],
  config: ConvertConfig = {},
): Wrapper {
  const posEntities: Record<string, DataEntity> = {};
  const keyEntities: Record<string, DataEntity> = {};
  let wrapper: Wrapper = { posEntities, keyEntities };
  if (config.initWrapper) {
    wrapper = config.initWrapper(wrapper) ?? wrapper;
  }

  traverseDataNodes(
    dataNodes,
    (item) => {
      const { node, index, pos, key, parentPos, level, nodes } = item;
      const entity: DataEntity = { node, nodes, index, key, pos, level };
      const mergedKey = getKey(key, pos);

      Object.defineProperty(posEntities, pos, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });
      Object.defineProperty(keyEntities, mergedKey, {
        value: entity,
        writable: true,
        configurable: true,
        enumerable: true,
      });

      entity.parent = Object.hasOwn(posEntities, parentPos) ? posEntities[parentPos] : undefined;
      if (entity.parent) {
        entity.parent.children = entity.parent.children || [];
        entity.parent.children.push(entity);
      }

      config.processEntity?.(entity, wrapper);
    },
    config,
  );

  config.onProcessFinished?.(wrapper);
  return wrapper;
}

// ================================ conduct ================================

export interface ConductResult {
  checkedKeys: string[];
  halfCheckedKeys: string[];
}

/** 上游 `isCheckDisabled`：`disabled` / `disableCheckbox` / `checkable === false`。 */
function isCheckDisabled(node: Record<string, unknown> | undefined): boolean {
  if (!node) return false;
  const { disabled, disableCheckbox, checkable } = node as {
    disabled?: boolean;
    disableCheckbox?: boolean;
    checkable?: boolean;
  };
  return !!(disabled || disableCheckbox) || checkable === false;
}

function removeFromCheckedKeys(
  halfCheckedKeys: Set<string>,
  checkedKeys: Set<string>,
): Set<string> {
  const filtered = new Set<string>();
  halfCheckedKeys.forEach((key) => {
    if (!checkedKeys.has(key)) filtered.add(key);
  });
  return filtered;
}

/** 按层级分组（上游 `conductCheck` 的第一步）。 */
function groupByLevel(keyEntities: Record<string, DataEntity>) {
  const levelEntities = new Map<number, Set<DataEntity>>();
  let maxLevel = 0;
  Object.keys(keyEntities).forEach((key) => {
    // noUncheckedIndexedAccess：索引访问可能 undefined（key 来自 Object.keys，防御式收窄）
    const entity = Object.hasOwn(keyEntities, key) ? keyEntities[key] : undefined;
    if (!entity) return;
    const { level } = entity;
    // ⚠️ 用局部变量接住（`get(...)!` 消不掉，且 `Map.get` 的返回类型永远是 `T | undefined`）
    let levelSet = levelEntities.get(level);
    if (!levelSet) {
      levelSet = new Set();
      levelEntities.set(level, levelSet);
    }
    levelSet.add(entity);
    maxLevel = Math.max(maxLevel, level);
  });
  return { levelEntities, maxLevel };
}

/** 自底向上：父的全部（非禁用）子是否都选中 / 部分选中。 */
function conductParent(
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  checkedKeys: Set<string>,
  halfCheckedKeys: Set<string>,
  getDisabled: (node: Record<string, unknown>) => boolean,
  onAllChecked: (parentKey: string) => void,
  onPartialChecked: (parentKey: string) => void,
): void {
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { node } = entity;
      const parent = entity.parent;
      if (!parent || getDisabled(node) || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const checked = checkedKeys.has(key);
          if (allChecked && !checked) allChecked = false;
          if (!partialChecked && (checked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (allChecked) onAllChecked(parent.key);
      if (partialChecked) onPartialChecked(parent.key);
      visitedKeys.add(parent.key);
    });
  }
}

function fillConductCheck(
  keys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  const halfCheckedKeys = new Set<string>();

  // 自顶向下：父选中 ⇒ 补子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (checkedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.add(childEntity.key);
          });
      }
    });
  }

  // 自底向上：子全选 ⇒ 补父；部分 ⇒ half
  conductParent(
    levelEntities,
    maxLevel,
    checkedKeys,
    halfCheckedKeys,
    getDisabled,
    (parentKey) => checkedKeys.add(parentKey),
    (parentKey) => halfCheckedKeys.add(parentKey),
  );

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

function cleanConductCheck(
  keys: Set<string>,
  halfKeys: Set<string>,
  levelEntities: Map<number, Set<DataEntity>>,
  maxLevel: number,
  getDisabled: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const checkedKeys = new Set(keys);
  let halfCheckedKeys = new Set(halfKeys);

  // 自顶向下：未选中且非半选 ⇒ 清掉子
  for (let level = 0; level <= maxLevel; level += 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach(({ key, node, children = [] }) => {
      if (!checkedKeys.has(key) && !halfCheckedKeys.has(key) && !getDisabled(node)) {
        children
          .filter((childEntity) => !getDisabled(childEntity.node))
          .forEach((childEntity) => {
            checkedKeys.delete(childEntity.key);
          });
      }
    });
  }

  // ⚠️ 自底向上必须**单遍**：`delete(parent.key)` 会立刻影响更高一层的判定
  //    （上游就是同一轮里先算 allChecked / partialChecked 再改 checkedKeys）。
  //    拆成两遍会让高层读到「本该删掉的父」，half 集合偏大。
  halfCheckedKeys = new Set<string>();
  const visitedKeys = new Set<string>();
  for (let level = maxLevel; level >= 0; level -= 1) {
    const entities = levelEntities.get(level) || new Set<DataEntity>();
    entities.forEach((entity) => {
      const { parent, node } = entity;
      if (getDisabled(node) || !parent || visitedKeys.has(parent.key)) return;
      if (getDisabled(parent.node)) {
        visitedKeys.add(parent.key);
        return;
      }
      let allChecked = true;
      let partialChecked = false;
      (parent.children || [])
        .filter((childEntity) => !getDisabled(childEntity.node))
        .forEach(({ key }) => {
          const isChecked = checkedKeys.has(key);
          if (allChecked && !isChecked) allChecked = false;
          if (!partialChecked && (isChecked || halfCheckedKeys.has(key))) partialChecked = true;
        });
      if (!allChecked) checkedKeys.delete(parent.key);
      if (partialChecked) halfCheckedKeys.add(parent.key);
      visitedKeys.add(parent.key);
    });
  }

  return {
    checkedKeys: Array.from(checkedKeys),
    halfCheckedKeys: Array.from(removeFromCheckedKeys(halfCheckedKeys, checkedKeys)),
  };
}

/**
 * 勾选传导。
 *
 * @param keyList 当前 key 列表
 * @param checked `true` = fill（补全）；`{ checked: false, halfCheckedKeys }` = clean（清理）
 * @param keyEntities `convertDataToEntities` 产出的 `keyEntities`
 */
export function conductCheck(
  keyList: string[],
  checked: true | { checked: false; halfCheckedKeys: string[] },
  keyEntities: Record<string, DataEntity>,
  getCheckDisabled?: (node: Record<string, unknown>) => boolean,
): ConductResult {
  const getDisabled = getCheckDisabled ?? isCheckDisabled;

  // 只处理存在的 key（上游会 warning 缺失的 key，本仓静默过滤）
  const keys = new Set(keyList.filter((key) => Object.hasOwn(keyEntities, key)));

  const { levelEntities, maxLevel } = groupByLevel(keyEntities);

  if (checked === true) {
    return fillConductCheck(keys, levelEntities, maxLevel, getDisabled);
  }
  return cleanConductCheck(
    keys,
    new Set(checked.halfCheckedKeys),
    levelEntities,
    maxLevel,
    getDisabled,
  );
}
```

---

# Checkbox

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/checkbox


一组备选项中进行多选。

## 何时使用

- 在一组备选项中进行多项选择时。
- 单独使用可以表示两种状态之间的切换（配合 `indeterminate` 可表达半选）。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/checkbox/demo)（8 个，覆盖 antd 的主要用户场景）。

## API

### Checkbox

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| checked | 指定当前是否选中（受控） | `boolean` | — |
| defaultChecked | 初始是否选中 | `boolean` | `false` |
| indeterminate | 设置 indeterminate 状态（只影响样式与 `input.indeterminate`） | `boolean` | `false` |
| disabled | 失效状态（`props ?? group.disabled ?? DisabledContext`） | `boolean` | — |
| value | ⚠️ 组外不是有效 prop（发 usage 告警）；在 Group 内是选项值 | `string \| number \| boolean` | — |
| skipGroup | 脱离 Group 的管理 | `boolean` | `false` |
| name / id / tabIndex / required / autoFocus / title | 原生属性（落到 `<input>` / `<span>`） | — | — |
| @change | 原生变化事件与提议 checked 快照 | `(event: Event, checked: boolean)` | — |
| @click / @mouseenter / @mouseleave / @focus / @blur / @keydown / @keypress | 控件拥有的原生事件（click 保留冒泡锁） | 原生事件 | — |
| classNames / styles | 语义槽 `{ root, icon, label }`（对象或函数） | — | — |

### CheckboxChangeEvent

`CheckboxChangeEvent` 是原生 `Event` 的类型别名。首参可直接用于 Vue 原生事件修饰符；第二参 checked 保留本次提议，即使受控父级拒绝提议后 input.checked 已恢复。旧 target DTO/nativeEvent 包装已移除。

### Checkbox.Group

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| options | 指定可选项（字符串/数字 ⇒ `{label, value}`；过滤空 value） | `(string \| number \| CheckboxOptionType)[]` | `[]` |
| value / defaultValue | 指定选中项（受控 / 非受控） | `T[]`（T 为 string/number/boolean） | `[]` |
| @change | 选中项变化通知（按 options/注册顺序排序、过滤已移除的值） | `(checkedValue: T[]) => void` | — |
| disabled | 整组失效（option 的 `disabled` 优先） | `boolean` | — |
| name | 组内全部 input 的 name（同时落根 div） | `string` | — |
| role | 根元素 role | `string` | `'group'` |
| class / style | Vue 原生根属性（含 style 字符串和数组） | — | — |

### 插槽

| 名称 | 说明 |
|---|---|
| default | Checkbox 文本（isRenderable 判据：`0` 渲染、`false`/`''` 不渲染） |
| Group default | 自定义子 Checkbox（与 options 二选一） |

受控父级拒绝提议时，原生勾选态恢复最后接受值；撤控不会接受被拒绝的值。`skipGroup` 动态切换会同步值注册，并脱离组的选中、disabled/name 管理。原生 input 的 value 使用实际选项值，可直接参与 FormData。当前 `components.checkbox` 的 className/style/classNames/styles 支持响应式替换。

## Ref

| 名称 | 类型 |
|---|---|
| nativeElement | `HTMLElement \| null` |
| input | `HTMLInputElement \| null` |
| focus / blur | `(options?: FocusOptions) => void` / `() => void` |

Group 通过 ref 暴露 `nativeElement: HTMLDivElement | null`；所有元素在挂载前或卸载后均为 null。

## Theme（Component Token）

无 —— Checkbox 没有任何 Component Token（antd 同），样式全部消费 alias token
（尺寸 = `controlInteractiveSize`）。用户想改样式用语义化 `classNames` / `styles`。


## 基本用法 (basic)

单独使用时受控 / 非受控均可；这里的 `checked` 状态展示在下方。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo（antd 在 onChange 里 console.log ⇒ 我们改为展示状态）
import { Checkbox } from '@apollo-design/ui';
import { ref } from 'vue';

const checked = ref(false);
const onChange = (_event: Event, next: boolean) => {
  checked.value = next;
};
</script>

<template>
  <div>
    <Checkbox @change="onChange">Checkbox</Checkbox>
    <p>checked = {{ checked }}</p>
  </div>
</template>
```

## 不可用 (disabled)

Checkbox 不可用（含半选态）。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 disabled demo
import { Checkbox, Flex } from '@apollo-design/ui';
</script>

<template>
  <!-- ⚠️ 加文字 children：axe 要求 label 有可访问名（上游同 demo 无文字但
       antd 的 a11y 基建对空 label 放行 —— 本仓按更严格标准） -->
  <Flex vertical gap="middle">
    <Checkbox :default-checked="false" disabled>Disabled unchecked</Checkbox>
    <Checkbox indeterminate disabled>Disabled indeterminate</Checkbox>
    <Checkbox default-checked disabled>Disabled checked</Checkbox>
  </Flex>
</template>
```

## 受控 (controller)

联合 Button 与 Checkbox 的受控用法。

### controller.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 controller demo
import { Button, Checkbox } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const checked = ref(true);
const disabled = ref(false);

const toggleChecked = () => {
  checked.value = !checked.value;
};
const toggleDisable = () => {
  disabled.value = !disabled.value;
};

const onChange = (_event: Event, next: boolean) => {
  checked.value = next;
};

const label = computed(
  () => `${checked.value ? 'Checked' : 'Unchecked'}-${disabled.value ? 'Disabled' : 'Enabled'}`,
);
</script>

<template>
  <div>
    <p style="margin-bottom: 20px">
      <Checkbox :checked="checked" :disabled="disabled" @change="onChange">{{ label }}</Checkbox>
    </p>
    <p>
      <Button type="primary" size="small" @click="toggleChecked">
        {{ !checked ? 'Check' : 'Uncheck' }}
      </Button>
      <Button style="margin: 0 10px" type="primary" size="small" @click="toggleDisable">
        {{ !disabled ? 'Disable' : 'Enable' }}
      </Button>
    </p>
  </div>
</template>
```

## 组 (group)

`Checkbox.Group` 与 `options` 的三种形态（字符串 / 对象 / 对象带 disabled）。

### group.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 group demo（antd 在 onChange 里 console.log ⇒ 移除）
import { Checkbox } from '@apollo-design/ui';

const plainOptions = ['Apple', 'Pear', 'Orange'];

const options = [
  { label: 'Apple', value: 'Apple', className: 'label-1' },
  { label: 'Pear', value: 'Pear', className: 'label-2' },
  { label: 'Orange', value: 'Orange', className: 'label-3' },
];

const optionsWithDisabled = [
  { label: 'Apple', value: 'Apple', className: 'label-1' },
  { label: 'Pear', value: 'Pear', className: 'label-2' },
  { label: 'Orange', value: 'Orange', className: 'label-3', disabled: false },
];
</script>

<template>
  <div>
    <Checkbox.Group :options="plainOptions" :default-value="['Apple']" />
    <br />
    <br />
    <Checkbox.Group :options="options" :default-value="['Pear']" />
    <br />
    <br />
    <Checkbox.Group :options="optionsWithDisabled" disabled :default-value="['Apple']" />
  </div>
</template>
```

## 全选 (check-all)

`indeterminate` 半选态实现全选效果。

### check-all.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 check-all demo
import { Checkbox, Divider } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const plainOptions = ['Apple', 'Pear', 'Orange'];
const checkedList = ref<string[]>(['Apple', 'Orange']);

const checkAll = computed(() => plainOptions.length === checkedList.value.length);
const indeterminate = computed(
  () => checkedList.value.length > 0 && checkedList.value.length < plainOptions.length,
);

const onCheckAllChange = (_event: Event, checked: boolean) => {
  checkedList.value = checked ? [...plainOptions] : [];
};
</script>

<template>
  <div>
    <Checkbox :indeterminate="indeterminate" :checked="checkAll" @change="onCheckAllChange">
      Check all
    </Checkbox>
    <Divider />
    <Checkbox.Group v-model:value="checkedList" :options="plainOptions" />
  </div>
</template>
```

## 布局 (layout)

`Checkbox.Group` 内嵌 `Row` / `Col` 自定义布局（children 与 options 二选一）。

### layout.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 layout demo
import { Checkbox, Col, Row } from '@apollo-design/ui';
</script>

<template>
  <Checkbox.Group>
    <Row>
      <Col :span="8">
        <Checkbox value="Apple">Apple</Checkbox>
      </Col>
      <Col :span="8">
        <Checkbox value="Pear">Pear</Checkbox>
      </Col>
      <Col :span="8">
        <Checkbox value="Orange">Orange</Checkbox>
      </Col>
    </Row>
  </Checkbox.Group>
</template>
```

## 语义化样式 (style-class)

通过 `classNames` / `styles` 自定义三槽（root / icon / label）。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo（语义化三槽：root / icon / label）
import { Checkbox } from '@apollo-design/ui';

const classNames = { root: 'demo-checkbox-root', label: 'demo-checkbox-label' };
const styles = {
  icon: { borderRadius: '50%' },
  label: { fontWeight: 600 },
};
</script>

<template>
  <Checkbox :class-names="classNames" :styles="styles">Semantic styles</Checkbox>
</template>

<style>
.demo-checkbox-root {
  border: 2px dashed #ccc;
  border-radius: 8px;
  padding: 8px;
}
.demo-checkbox-label {
  color: #1677ff;
}
</style>
```

## 自定义线宽 (custom-line-width)

> 等价替换：antd 用 `ConfigProvider theme.token.lineWidth` 改边框宽度；本仓的全局
> token 经 CSS 变量注入，这里直接用语义化 `styles.icon` 演示同等视觉。

通过 `styles.icon` 自定义边框粗细（等价于 antd 的 token 定制演示）。

### custom-line-width.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 custom-line-width demo
// ⚠️ PLATFORM 替换：antd 用 ConfigProvider theme.token.lineWidth；本仓无
//    theme token 注入，用语义化 styles.icon 演示同等视觉（README §2 登记）。
import { Checkbox } from '@apollo-design/ui';

const styles = {
  icon: { borderWidth: '3px' },
};
</script>

<template>
  <Checkbox :styles="styles">lineWidth = 3px</Checkbox>
</template>
```

---

# Collapse

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/collapse


使用标题按钮展开内容，适合 FAQ、设置分组。支持数据驱动的 `items` 和声明式 `CollapsePanel`；两者使用同一个真实 Vue 组件。全部 9 个示例见 [demo](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/collapse/demo)。

## API

### Collapse

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| items | 面板数据；数组存在时优先于默认插槽，空数组也优先 | `CollapseItemType[]` | — |
| activeKey / defaultActiveKey | 受控值 / 一次性初始化值，key 统一为字符串 | `string \| number \| (string \| number)[]` | — |
| accordion | 同时只展开一个；仍使用 disclosure 语义 | `boolean` | `false` |
| bordered / ghost | 边框 / 透明模式 | `boolean` | `true` / `false` |
| size | 局部尺寸；未设置时继承 Provider componentSize | `'small' \| 'middle' \| 'large'` | `middle` |
| collapsible | 默认整行空白与标题按钮；header 仅标题按钮；icon 仅图标按钮；disabled 禁止切换 | `'header' \| 'icon' \| 'disabled'` | — |
| headingLevel | 标题层级；嵌套 Collapse 默认递增，最多 6 | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` |
| expandIconPlacement | 图标的逻辑位置；extra 为独立区域 | `'start' \| 'end'` | `start` |
| destroyOnHidden | 完成关闭后销毁正文；forceRender 优先 | `boolean` | `false` |
| prefixCls | 完整组件前缀，需预载相应静态 CSS | `string` | Provider 前缀 + `-collapse` |
| classNames / styles | root、header、title、body、icon 五个语义区域 | `CollapseSemanticClassNames / CollapseSemanticStyles` | — |

`destroyInactivePanel`、`expandIconPosition` 分别是 destroyOnHidden、expandIconPlacement 的旧别名，会开发告警，新字段优先。原生 class、style、ARIA、data、role 与原生监听器透传到根。native style 的同名变量优先于 Provider 和语义 root 样式。

| 插槽 | 内容 / scope |
|---|---|
| default | 声明式 CollapsePanel；有 items 数组时不读取 |
| expandIcon | `{ key, isActive, prefixCls, collapsible, direction }`；存在即优先，支持 Fragment、0 和空内容 |

顶层 expandIcon 渲染 prop 已按开发版槽位规范迁移为 `#expandIcon`。程序化默认工厂仍可配置在 `ConfigProvider components.collapse.expandIcon`；局部插槽优先。

| 事件 | 载荷 |
|---|---|
| update:activeKey | `string[]`；支持 `v-model:active-key` |
| change | `string[]`；每次允许的激活恰好一次 |

受控激活只提出请求，父级未接受时不改变展示。解除受控使用最后实际接受的值；defaultActiveKey 的后续变化不重置状态。ref 暴露 `nativeElement: HTMLDivElement | null`。

### CollapseItemType 与 CollapsePanel

| 字段 | items | Panel |
|---|---|---|
| key | string / number；默认数组下标 | Vue key；省略时按初次挂载顺序编号，动态面板应显式指定稳定 key |
| label / header | VNode 数据，label 优先 | header 为 string；其次 label 为 VNode 数据 |
| children / extra | VNode 数据，可为 0 / Fragment | 使用 default / #extra 插槽 |
| showArrow / forceRender | boolean，默认 true / false | 相同 |
| collapsible / destroyOnHidden | 覆盖所属 Collapse | 相同 |
| onItemClick / @item-click | 一次激活收到归一后的 string key | Vue 事件，支持 .once |
| className / style | 当前 item 根的类名 / 原生 StyleValue | 相同，并支持原生 class、attrs 和监听器 |
| classNames / styles | 五区域，局部覆盖全局；root 仅作用于 item | 相同 |
| headerClass / id | header 类名 / item 根 id | 相同 |
| prefixCls | — | 本 Panel 完整前缀；继承所属 Collapse Token，需预载该前缀 CSS |
| disabled | — | 旧禁用输入并告警；显式 collapsible 优先 |

Panel 的 `#header` 存在时覆盖 header 和 label，包括明确空内容；移除条件 slot 才回退。标题放在真实 heading/button 中，使用 span、文字等标题内容；独立按钮、输入框等交互内容应放入 `#extra`。extra 位于 heading 与按钮之外，无需阻止冒泡。默认插槽为正文；Panel 本身支持正常 Vue 生命周期。

## 键盘、内容与动画

Tab 聚焦标题按钮，Enter / Space 切换。禁用按钮不可激活；icon 配合 showArrow=false 时明确禁用并开发告警。空自定义图标仍保留可操作且有名称的按钮。标题为空时使用默认可访问名称；应用宜提供有意义的标题。

正文首次展开时挂载，默认在完成关闭后保留 DOM、表单状态和选区；关闭内容 hidden / inert。destroyOnHidden 仅销毁正文，稳定 region 与 aria-controls 关系保留。forceRender 始终渲染并保留正文，优先于 destroyOnHidden。关闭时若焦点位于该正文，则移回所属标题；外部焦点保持原位。动画响应当前主题 motion、系统减少动画及当前前缀。

如果外部关闭正文时其标题按钮已被禁用，焦点回到所属 Collapse 容器；容器只在持有此焦点时临时使用 tabindex=-1，离焦后恢复原生 attrs。

## 主题

当前 `theme.components.Collapse` 支持十个 CSS 字符串 Token：headerPadding、headerPaddingSM、headerPaddingLG、headerBg、contentPadding、contentPaddingSM、contentPaddingLG、contentBg、borderlessContentPadding、borderlessContentBg。对应 `--<组件前缀>-header-padding` 等变量；ghost 视觉为透明背景。

默认 padding 和派生 panel radius 读取当前 Alias；contentPadding 的默认横向 16px 为设计常数。borderlessContentBg 默认 transparent。显式空 ThemeProvider 恢复默认；CSS-only 场景保留继承变量。详情与迁移见 [Collapse 开发版迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/collapse-contracts.md)。


## 基本 (basic)

`items` 数据驱动；标题原生按钮支持点击、Enter、Space（默认可多开）。正文首次展开时挂载，默认在折叠后保留。

### basic.vue

```vue
<script setup lang="ts">
// 数据驱动面板；标题按钮支持鼠标、Enter 与 Space。
import { Collapse } from '@apollo-design/ui';

const items = [
  {
    key: '1',
    label: 'This is panel header 1',
    children: 'A dog is a type of domesticated animal.',
  },
  {
    key: '2',
    label: 'This is panel header 2',
    children: 'A dog is a type of domesticated animal.',
  },
  {
    key: '3',
    label: 'This is panel header 3',
    children: 'A dog is a type of domesticated animal.',
  },
];
</script>

<template>
  <Collapse :items="items" />
</template>
```

## 手风琴 (accordion)

`accordion` 同时只展开一个面板。标题仍为原生 heading/button，使用 Tab、Enter 和 Space 操作。

### accordion.vue

```vue
<script setup lang="ts">
// accordion 保留 disclosure 语义，同时仅展开一个面板。
import { Collapse } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'This is panel header 1', children: 'Content' },
  { key: '2', label: 'This is panel header 2', children: 'Content' },
  { key: '3', label: 'This is panel header 3', children: 'Content' },
];
</script>

<template>
  <Collapse :items="items" accordion />
</template>
```

## 无边框 / 幽灵模式 (borderless)

`bordered={false}` 去外框（分隔线保留）；`ghost` 全透明。

### borderless.vue

```vue
<script setup lang="ts">
// 无边框保留分隔线；ghost 使用透明背景。
import { Collapse } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'This is panel header 1', children: 'Content' },
  { key: '2', label: 'This is panel header 2', children: 'Content' },
];
</script>

<template>
  <Collapse :items="items" :bordered="false" style="margin-bottom: 24px" />
  <Collapse :items="items" ghost />
</template>
```

## 额外节点与交互模式 (extra)

`#extra` 渲染在标题按钮之外，保存操作无需阻止冒泡，也不会改变展开状态。`collapsible` 支持 header、icon、disabled；禁用时保留当前状态。

### extra.vue

```vue
<script setup lang="ts">
import { Button, Collapse, CollapsePanel } from '@apollo-design/ui';
import { ref } from 'vue';

const saved = ref(0);
</script>

<template>
  <div>
    <p aria-live="polite">已保存 {{ saved }} 次</p>
    <Collapse>
      <CollapsePanel key="1" header="带独立操作的面板">
        <template #extra><Button size="small" @click="saved += 1">保存</Button></template>
        extra 的按钮独立响应点击、Enter 和 Space，不改变展开状态。
      </CollapsePanel>
      <CollapsePanel key="2" header="仅标题按钮可展开" collapsible="header">Content</CollapsePanel>
      <CollapsePanel key="3" header="禁止折叠" collapsible="disabled">Content</CollapsePanel>
    </Collapse>
  </div>
</template>
```

## 可折叠交互 (collapsible)

通过 `collapsible` 在 header、icon、disabled 三种折叠交互间切换，并用 `v-model:active-key` 实时展示当前展开的面板。

### collapsible.vue

```vue
<script setup lang="ts">
import type { CollapseItemType, CollapsibleType } from '@apollo-design/ui';
import { Collapse, Select, Space, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const collapsible = ref<CollapsibleType>('header');
const activeKey = ref<string[]>(['1']);

const collapsibleOptions: { value: CollapsibleType; label: string }[] = [
  { value: 'header', label: 'header（点击标题）' },
  { value: 'icon', label: 'icon（仅点击图标）' },
  { value: 'disabled', label: 'disabled（禁止折叠）' },
];

const items: CollapseItemType[] = [
  {
    key: '1',
    label: '面板一：点击区域由 collapsible 决定',
    children: 'header 模式点击标题按钮；icon 模式只激活图标按钮。两者均支持 Enter 与 Space。',
  },
  {
    key: '2',
    label: '面板二：切换模式后再试试',
    children: '选择 icon 后只有箭头按钮可操作；选择 disabled 后保留当前展开状态，且不能切换。',
  },
];

function onCollapsibleChange(value: unknown): void {
  if (value === 'header' || value === 'icon' || value === 'disabled') collapsible.value = value;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>collapsible</span>
      <Select
        aria-label="折叠触发方式"
        :value="collapsible"
        :options="collapsibleOptions"
        style="width: 220px"
        @change="onCollapsibleChange"
      />
      <Tag color="blue">{{ collapsible }}</Tag>
      <Tag>当前展开：{{ activeKey.length ? activeKey.join('、') : '无' }}</Tag>
    </Space>

    <Collapse v-model:active-key="activeKey" :items="items" :collapsible="collapsible" />
  </div>
</template>
```

## 自定义标题与操作 (custom)

使用真实 `CollapsePanel` 的 `#header`、`#extra` 与根 `#expandIcon` 插槽组合标题、独立通知按钮和展开图标。正文编辑器在默认折叠后保留草稿；`headingLevel` 可指定文档层级。

### custom.vue

```vue
<script setup lang="ts">
import { Button, Collapse, CollapsePanel, Input, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const notifyCount = ref(0);
const draft = ref('');
</script>

<template>
  <div>
    <p aria-live="polite">通知次数：{{ notifyCount }}</p>
    <Collapse default-active-key="production" :heading-level="3">
      <template #expandIcon="{ isActive }">
        <span aria-hidden="true">{{ isActive ? '−' : '+' }}</span>
      </template>
      <CollapsePanel key="production">
        <template #header>
          <span style="font-weight: 600">生产环境部署</span>
          <Tag color="blue" style="margin-inline-start: 8px">推荐</Tag>
        </template>
        <template #extra>
          <Button size="small" @click="notifyCount += 1">发送通知</Button>
        </template>
        <label style="display: grid; gap: 8px">部署备注 <Input v-model:value="draft" placeholder="折叠后保留草稿" /></label>
        <p>草稿：{{ draft || '尚未填写' }}</p>
      </CollapsePanel>
      <CollapsePanel key="staging" header="预发环境部署">
        <template #extra><Tag color="orange">待审批</Tag></template>
        标题、图标和独立 extra 操作都由真实 Vue 插槽渲染。
      </CollapsePanel>
    </Collapse>
  </div>
</template>
```

## 幽灵模式 (ghost)

使用 `ghost` 移除折叠面板的背景与边框，开关可实时对比幽灵模式与默认样式。

### ghost.vue

```vue
<script setup lang="ts">
import type { CollapseItemType } from '@apollo-design/ui';
import { Collapse, Space, Switch, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const ghost = ref(true);

const items: CollapseItemType[] = [
  {
    key: '1',
    label: 'ghost 面板标题',
    children: 'ghost 模式会移除背景与边框，让折叠面板融入外层容器。',
  },
  {
    key: '2',
    label: '第二个面板',
    children: '切换开关即可对比默认边框与幽灵模式的差异。',
  },
];
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>ghost</span>
      <Switch
        v-model:checked="ghost"
        checked-children="开启"
        un-checked-children="关闭"
      />
      <Tag color="blue">{{ ghost ? '透明背景 + 无边框' : '默认背景 + 边框' }}</Tag>
    </Space>

    <div class="ghost-demo-stage">
      <Collapse :items="items" :ghost="ghost" />
    </div>
  </div>
</template>

<style scoped>
.ghost-demo-stage {
  padding: 16px;
  border-radius: var(--apollo-border-radius-lg);
  background: var(--apollo-color-fill-secondary);
}
</style>
```

## 尺寸 (size)

通过 `size` 在 small、middle、large 之间切换，标题与内容区的内边距会随尺寸实时变化。

### size.vue

```vue
<script setup lang="ts">
import type { CollapseItemType, CollapseProps } from '@apollo-design/ui';
import { Collapse, Select, Space, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

type CollapseSize = NonNullable<CollapseProps['size']>;

const size = ref<CollapseSize>('middle');

const sizeOptions: { value: CollapseSize; label: string }[] = [
  { value: 'small', label: 'small' },
  { value: 'middle', label: 'middle' },
  { value: 'large', label: 'large' },
];

const items: CollapseItemType[] = [
  {
    key: '1',
    label: '面板尺寸',
    children: '切换尺寸会同步改变标题区与内容区的内边距。',
  },
  {
    key: '2',
    label: '第二个面板',
    children: 'size 支持 small、middle、large 三种取值。',
  },
];

function onSizeChange(value: unknown): void {
  if (value === 'small' || value === 'middle' || value === 'large') size.value = value;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>size</span>
      <Select
        aria-label="面板尺寸"
        :value="size"
        :options="sizeOptions"
        style="width: 140px"
        @change="onSizeChange"
      />
      <Tag color="blue">{{ size }}</Tag>
    </Space>

    <Collapse :items="items" :size="size" />
  </div>
</template>
```

## 组件 Token (component-token)

通过当前 `ConfigProvider theme.components.Collapse` 实时配置全部十个组件 Token，并保持颜色与当前主题一致。展示普通和无边框内容，切换宽松间距可比较默认及 small 的内边距。

### component-token.vue

```vue
<script setup lang="ts">
import { useTheme } from '@apollo-design/theme';
import type { CollapseItemType } from '@apollo-design/ui';
import { Checkbox, Collapse, ConfigProvider } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const source = useTheme();
const spacious = ref(false);
const theme = computed(() => ({
  components: {
    Collapse: {
      headerPadding: spacious.value ? '20px 24px' : '12px 16px',
      headerPaddingSM: spacious.value ? '14px 18px' : '8px 12px',
      headerPaddingLG: spacious.value ? '24px 28px' : '16px 24px',
      headerBg: source.token.value.colorFillSecondary,
      contentPadding: spacious.value ? '24px' : '16px',
      contentPaddingSM: spacious.value ? '18px' : '12px',
      contentPaddingLG: spacious.value ? '28px' : '24px',
      contentBg: source.token.value.colorBgContainer,
      borderlessContentPadding: spacious.value ? '12px 24px 20px' : '4px 16px 16px',
      borderlessContentBg: source.token.value.colorFillAlter,
    },
  },
}));
const items: CollapseItemType[] = [
  {
    key: '1',
    label: '当前 Provider 的组件 Token',
    children: '切换间距配置会实时更新这十个组件 Token；颜色沿用当前主题。',
  },
  {
    key: '2',
    label: '无边框内容背景',
    children: 'borderlessContentBg 同样由 theme.components.Collapse 消费。',
  },
];
</script>

<template>
  <div>
    <Checkbox v-model:checked="spacious">宽松间距</Checkbox>
    <ConfigProvider :theme="theme">
      <Collapse :items="items" default-active-key="1" style="margin-block: 16px" />
      <Collapse :items="items" :bordered="false" size="small" default-active-key="2" />
    </ConfigProvider>
  </div>
</template>
```

---

# ColorPicker

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/color-picker


提供颜色选取的组件：点击触发器弹出取色面板，支持单色 / 渐变色、预设色板与多种编码格式。

## 何时使用

- 需要让用户选取一个颜色（或一段渐变色）时；
- 需要用预设色板让用户快速取色时；
- 需要在表单里以**受控**方式维护颜色值时。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/color-picker/demo)（**16 个**，覆盖 antd 的主要用户场景）。

| demo | 内容 |
|---|---|
| `base` | 最简用法（`defaultValue` + 触发器） |
| `size` | 触发器 `small` / 默认 / `large` 三档（含 `showText`） |
| `controlled` | `value` + `@change` / `@changeComplete` 两种受控节奏 |
| `line-gradient` | `mode` 单色 / 渐变（可多选） |
| `text-render` | 默认文本与原生 #showText 作用域插槽 |
| `disabled` | 禁用态 |
| `disabled-alpha` | `disabledAlpha` 去掉透明度 |
| `allowClear` | 清空入口与「已清空」态 |
| `trigger` | 默认插槽自定义触发器 |
| `trigger-event` | `trigger="hover"` |
| `format` | `format` 的 `hex` / `hsb` / `rgb` |
| `presets` | 分组预设色 |
| `presets-line-gradient` | 渐变预设色 |
| `panel-render` | `panelRender` 自由接管面板 |
| `style-class` | `classNames` / `styles` 的对象 / 函数形态 |
| `pure-panel` | `ColorPickerPurePanel` 静态面板 |

⚠️ 上游的 `_semantic` demo（文档的「语义化 DOM」示意，`simplify` 专用）**不落地**；
语义槽的覆盖由 `semantic.test.ts` 承担。

## API

原生 `class`、`id`、ARIA 和鼠标监听器落在触发器；Vue 模板的 `@mousedown` 等已知原生事件及 Once/Passive/Capture 后缀保留。仅更新 attrs 时也会读取当前值，监听器替换不重复调用。

### Props

| 参数 | 说明 | 类型 | 默认值 | 全局配置 |
|---|---|---|---|---|
| mode | 模式：单色 / 渐变（可多选） | `'single' \| 'gradient' \| ModeType[]` | `'single'` | × |
| value | 受控值（配合 `v-model:value`） | `ColorValueType` | — | × |
| defaultValue | 非受控初值。**都不传 ⇒ 「已清空」态** | `ColorValueType` | — | × |
| format | 当前编码格式（配合 `v-model:format`） | `'hex' \| 'rgb' \| 'hsb'` | `'hex'` | × |
| defaultFormat | 非受控初始格式 | `'hex' \| 'rgb' \| 'hsb'` | — | × |
| disabledFormat | 是否禁用格式下拉（下拉没了，输入框仍在） | `boolean` | `false` | × |
| open | 受控开合（配合 `v-model:open`） | `boolean` | — | × |
| trigger | 触发方式 | `'click' \| 'hover'` | `'click'` | × |
| placement | 浮层位置 | `TriggerPlacement` | `'bottomLeft'` | × |
| arrow | 是否显示箭头 | `boolean \| { pointAtCenter?: boolean }` | 跟随 ConfigProvider | ✅ |
| getPopupContainer | 浮层挂载容器 | `(triggerNode: HTMLElement) => HTMLElement` | — | × |
| autoAdjustOverflow | 溢出自动调整 | `boolean` | `true` | × |
| destroyTooltipOnHide | ⚠️ **已废弃**，请用 `destroyOnHidden` | `boolean \| { keepParent?: boolean }` | `false` | × |
| destroyOnHidden | 关闭后卸载浮层 | `boolean` | `false` | × |
| allowClear | 是否允许清空 | `boolean` | `false` | × |
| disabledAlpha | 禁用 alpha（面板不渲染 alpha 滑块与输入；半透明色会被强制为不透明） | `boolean` | `false` | × |
| presets | 预设面板（**数组**才渲染，且会多一条 `Divider`） | `PresetsItem[]` | — | × |
| showText | 显示默认文本；自定义内容用 #showText | `boolean` | `false` | × |
| size | 尺寸 | `'small' \| 'middle' \| 'large' \| string` | 跟随 ConfigProvider | ✅ |
| disabled | 禁用 | `boolean` | 跟随 ConfigProvider | ✅ |

| classNames | 语义化类名（`root` / `body` / `content` / `description` / `popup`），支持函数形态 | `ColorPickerSemanticClassNames \| ((info) => …)` | — | ✅ |
| styles | 语义化样式（6 个槽，比 `classNames` 多一个 `popupOverlayInner`），支持函数形态 | `ColorPickerSemanticStyles \| ((info) => …)` | — | ✅ |
| prefixCls | 类名前缀 | `string` | 从 ConfigProvider 取，兜底 `apollo-color-picker` | × |
| class / style | 原生 attrs 作用于实际触发器；浮层使用 popup.root | Vue class / StyleValue | — | × |

#### ColorValueType

```ts
type SingleValueType = AggregationColor | string;
type LineGradientType = { color: SingleValueType; percent: number }[];
type ColorValueType = SingleValueType | null | LineGradientType;
```

⚠️ **「清空」不是 `null`，而是 alpha=0 的颜色实例 + `cleared = true`**。触发器据此
在 `ColorClear`（透明棋盘格）与 `ColorBlock`（色块）之间切换。

Color 实例的数字输入表示 0x000000–0xffffff 的整数 RGB；对象通道支持有限数字与数字字符串，HSB 的 s/b 为 0–1。非法数字会抛出可定位的输入错误，不转成默认颜色。

#### PresetsItem

| 字段 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| label | 分组标题 | `VNodeChild` | — |
| colors | 该组颜色（字符串 / 颜色实例 / **渐变**） | `(string \| AggregationColor \| LineGradientType)[]` | — |
| defaultOpen | 初始是否展开 | `boolean` | `true` |
| key | 分组 key（不传用下标） | `string \| number` | — |

### Events

| 事件 | 说明 | 参数 |
|---|---|---|
| update:value | `v-model:value` 的更新通道（与 `change` **双发**） | `(value: Color)` |
| change | 值变化。⚠️ 第二个参数是 `toCssString()` 的 CSS 串 | `(value: Color, css: string)` |
| changeComplete | 值变化**完成**。⚠️ **拖拽期间不发** | `(value: Color)` |
| clear | 清空 | — |
| update:open | `v-model:open` 的更新通道（与 `openChange` **双发**） | `(open: boolean)` |
| openChange | 开合变化 | `(open: boolean)` |
| update:format | `v-model:format` 的更新通道（与 `formatChange` **双发**） | `(format?: ColorFormatType)` |
| formatChange | 格式变化。⚠️ **同值不发** | `(format?: ColorFormatType)` |

### Slots

| 插槽 | 说明 | 参数 |
|---|---|---|
| default | 触发器内容（等价上游 `children`）。传了就**完全不要**内置触发器 | — |
| panelRender | 自定义面板；panel 是稳定的 Vue 组件引用 | `{ panel: Component; extra: ColorPickerPanelRenderExtra }` |
| showText | 自定义触发器文字，按当前插槽存在性渲染完整内容 | `{ color: Color }` |

`extra.components` 提供 `{ Picker, Presets }` 两个组件引用，供自定义面板自行编排：

```vue
<script setup lang="ts">
import { ColorPicker } from '@apollo-design/ui';
</script>

<template>
  <ColorPicker default-value="#1677ff">
    <template #panelRender="{ panel }">
      <section>
        <p>Color Picker</p>
        <component :is="panel" />
      </section>
    </template>
    <template #showText="{ color }">{{ color.toHexString() }}</template>
  </ColorPicker>
</template>
```

### Methods

本轮不新增命令或 Expose 接口。

### Design Token

**用户可覆盖的 Component Token：0 个**（与 antd 一致）。

九个样式派生值使用 --apollo-color-picker-* CSS 变量，不是 theme.components.ColorPicker 的配置字段。当前主题别名同步到触发器与弹层；需要自定义派生样式时，在对应宿主覆盖 CSS 变量：

| 变量 | 值 |
|---|---|
| `--apollo-color-picker-width` | `234px` |
| `--apollo-color-picker-handler-size` | `16px` |
| `--apollo-color-picker-handler-size-sm` | `12px` |
| `--apollo-color-picker-alpha-input-width` | `44px` |
| `--apollo-color-picker-input-number-handle-width` | `16px` |
| `--apollo-color-picker-preset-color-size` | `24px` |
| `--apollo-color-picker-inset-shadow` | `inset 0 0 1px 0 var(--apollo-color-text-quaternary)` |
| `--apollo-color-picker-slider-height` | `8px` |
| `--apollo-color-picker-preview-size` | `calc(var(--apollo-color-picker-slider-height) * 2 + var(--apollo-margin-sm))` |

### 语义化 DOM

| 槽 | 落在哪 |
|---|---|
| `root` | 原生触发按钮（自定义触发器时为所属宿主） |
| `body` | 触发器里的色块 / 透明棋盘格 |
| `content` | 色块**内层**（`ColorBlock` 的 inner） |
| `description` | 触发器右侧文本容器 |
| `popup.root` | 浮层根节点（**嵌套槽**） |
| `popupOverlayInner` | ⚠️ **只有 `styles` 有**，映射到 Popover 的 `styles.container` |

⚠️ `classNames` 5 个槽、`styles` 6 个槽，**故意不对称**（与上游一致）。

## FAQ

### 为什么 `defaultValue` 不传时触发器是透明棋盘格？

因为上游的默认值就是「已清空」—— `useModeColor` 拿到 `undefined` ⇒
`AggregationColor` 走 `cleared` 分支（alpha=0）。想看到颜色请显式给 `defaultValue`。

### `disabledAlpha` 为什么把半透明色改写了？

disabledAlpha 下，新输入在 change / changeComplete 中归一为不透明；渐变逐段处理，不扁平化为单色。清空动作保留其独立语义。

### 开发版迁移

- 删除 panelRender 函数 prop，改用 #panelRender；作用域 panel 现在是稳定的 Vue 组件引用，可直接写 <component :is="panel" />。
- showText 只接受 boolean，函数内容改为 #showText，作用域提供当前 color。条件槽与空槽按存在性处理。
- 默认触发器、预设选择和面板清空使用原生 button；触发器内清空图形为不可聚焦装饰。原始参考保留，语义测试只派生这组已说明的差异。
- size 使用共享 SizeType，不接受任意字符串。原生 class/style 只作用于触发器；浮层用 classNames.popup.root/styles.popup.root，内部容器用 styles.popupOverlayInner。
- 受控开关/格式拒绝的请求不泄漏到撤控状态；disabledAlpha 归一新输入的每个渐变段，清空动作保持 cleared。
- PurePanel 在正常文档流展示真实面板；原生 attrs 落宿主，panelRender 槽与 Vue 事件真实转发，不再轮询尺寸。


## 基本 (base)

最简单的用法：给一个 `defaultValue`，点击触发器即可取色。

### base.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 base demo：最简用法。
import { ColorPicker } from '@apollo-design/ui';
</script>

<template>
  <ColorPicker default-value="#1677ff" />
</template>
```

## 触发器尺寸大小 (size)

触发器有 `small` / 默认 / `large` 三档尺寸，可配合 `showText` 一起用。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size demo：触发器大 / 中 / 小三档（含 `showText` 两列）。
import { ColorPicker, Space } from '@apollo-design/ui';
</script>

<template>
  <Space>
    <Space vertical>
      <ColorPicker default-value="#1677ff" size="small" />
      <ColorPicker default-value="#1677ff" />
      <ColorPicker default-value="#1677ff" size="large" />
    </Space>
    <Space vertical>
      <ColorPicker default-value="#1677ff" size="small" show-text />
      <ColorPicker default-value="#1677ff" show-text />
      <ColorPicker default-value="#1677ff" size="large" show-text />
    </Space>
  </Space>
</template>
```

## 受控模式 (controlled)

`value` + `@change` 让组件受控；换成 `@changeComplete` 则**拖拽结束**才同步，展示色会被「锁住」。

### controlled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 controlled demo：两个受控 ColorPicker 共享同一份颜色状态。
// 第一个由 `onChange` 驱动（拖拽中实时同步），第二个由 `onChangeComplete` 驱动
// （拖拽结束才同步 ⇒ 视觉上「锁住」展示色）。
import type { ColorPickerColor, ColorValueType } from '@apollo-design/ui';
import { ColorPicker, Space } from '@apollo-design/ui';
import { ref } from 'vue';

/** 上游 `Color`（= `AggregationColor`）：ui barrel 未导出该别名，从 `change` 的载荷反推。 */
type Color = ColorPickerColor;

const color = ref<ColorValueType>('#1677ff');

const onChange = (c: Color) => {
  color.value = c;
};

const onChangeComplete = (c: Color) => {
  color.value = c;
};
</script>

<template>
  <Space>
    <ColorPicker :value="color" @change="onChange" />
    <ColorPicker :value="color" @change-complete="onChangeComplete" />
  </Space>
</template>
```

## 渐变色 (line-gradient)

`mode` 决定面板支持单色还是渐变色（可多选）；渐变值形如 `[{ color, percent }]`。

### line-gradient.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 line-gradient demo：用 `mode` 切换单色 / 渐变色。
import type { ColorPickerColor } from '@apollo-design/ui';
import { ColorPicker, Space } from '@apollo-design/ui';

/** 上游 `Color`（= `AggregationColor`）：ui barrel 未导出该别名，从 `change` 的载荷反推。 */
type Color = ColorPickerColor;

const DEFAULT_COLOR = [
  { color: 'rgb(16, 142, 233)', percent: 0 },
  { color: 'rgb(135, 208, 104)', percent: 100 },
];

// 上游在 `onChangeComplete` 里 `console.log(color.toCssString())` —— 本仓同。
const onChangeComplete = (color: Color) => {
  console.log(color.toCssString());
};
</script>

<template>
  <Space vertical>
    <ColorPicker
      :default-value="DEFAULT_COLOR"
      allow-clear
      show-text
      :mode="['single', 'gradient']"
      @change-complete="onChangeComplete"
    />
    <ColorPicker
      :default-value="DEFAULT_COLOR"
      allow-clear
      show-text
      mode="gradient"
      @change-complete="onChangeComplete"
    />
  </Space>
</template>
```

## 渲染触发器文本 (text-render)

showText 显示默认颜色文本；#showText 自定义内容，作用域提供当前 color。

### text-render.vue

```vue
<script setup lang="ts">
import { DownOutlined } from '@apollo-design/icons';
import { ColorPicker, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
</script>

<template>
  <Space vertical>
    <ColorPicker default-value="#1677ff" show-text allow-clear />
    <ColorPicker default-value="#1677ff">
      <template #showText="{ color }">Custom Text ({{ color.toHexString() }})</template>
    </ColorPicker>
    <ColorPicker v-model:open="open" default-value="#1677ff">
      <template #showText><DownOutlined :rotate="open ? 180 : 0" /></template>
    </ColorPicker>
  </Space>
</template>
```

## 禁用 (disabled)

`disabled` 禁用整个组件；触发器仍会渲染当前颜色。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 disabled demo：禁用状态 + 展示文本。
import { ColorPicker } from '@apollo-design/ui';
</script>

<template>
  <ColorPicker default-value="#1677ff" show-text disabled />
</template>
```

## 禁用透明度 (disabled-alpha)

`disabledAlpha` 去掉 alpha 滑块与 alpha 输入，并把半透明色强制为不透明。

### disabled-alpha.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 disabled-alpha demo：禁用透明度。
// ⚠️ 默认值用**不透明**色（`#1677ff`）—— 半透明色 + `disabledAlpha` 会触发上游同款的
//    「alpha 被强制为 100%」开发期告警（本 demo 有意不触发它）。
import { ColorPicker } from '@apollo-design/ui';
</script>

<template>
  <ColorPicker default-value="#1677ff" disabled-alpha />
</template>
```

## 清除颜色 (allowClear)

`allowClear` 在面板操作条与触发器上给出清空入口；清空后触发器渲染成透明棋盘格。

### allowClear.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 allowClear demo：受控值 + 清空按钮。
//
// ⚠️ **一处 demo 级替换**：上游 `value` 收 `string`、`onChange` 里 `c.toHexString()` 回写
//    —— 本仓 `value` 走 `:value` + `@change` 的受控通道（C11），语义逐字对应。
import type { ColorPickerColor } from '@apollo-design/ui';
import { ColorPicker } from '@apollo-design/ui';
import { ref } from 'vue';

/** 上游 `Color`（= `AggregationColor`）：ui barrel 未导出该别名，从 `change` 的载荷反推。 */
type Color = ColorPickerColor;

const color = ref<string>('#1677ff');

const onChange = (c: Color) => {
  color.value = c.toHexString();
};
</script>

<template>
  <ColorPicker :value="color" allow-clear @change="onChange" />
</template>
```

## 自定义触发器 (trigger)

`children`（默认插槽）可完全替换内置触发器。

### trigger.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 trigger demo：用**默认插槽**自定义触发器（本仓 `children` 走默认插槽）。
import type { ColorPickerColor } from '@apollo-design/ui';
import { Button, ColorPicker } from '@apollo-design/ui';
import { computed, ref } from 'vue';

/** 上游 `Color`（= `AggregationColor`）：ui barrel 未导出该别名，从 `change` 的载荷反推。 */
type Color = ColorPickerColor;

// ⚠️ 收窄成 `Color | string`（上游 demo 的 `Extract<…, string | {cleared}>` 同判）：
//    `ColorValueType` 还含 `null` / 渐变数组，它们没有 `toHexString()`。
const color = ref<Color | string>('#1677ff');

const bgColor = computed(() =>
  typeof color.value === 'string' ? color.value : color.value.toHexString(),
);

const onChange = (c: Color) => {
  color.value = c;
};
</script>

<template>
  <ColorPicker :value="color" @change="onChange">
    <Button type="primary" :style="{ backgroundColor: bgColor }">open</Button>
  </ColorPicker>
</template>
```

## 自定义触发事件 (trigger-event)

`trigger` 只有两档：`click`（默认）与 `hover`。

### trigger-event.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 trigger-event demo：`trigger="hover"` 用悬停打开面板。
import { ColorPicker } from '@apollo-design/ui';
</script>

<template>
  <ColorPicker default-value="#1677ff" trigger="hover" />
</template>
```

## 颜色编码 (format)

`format` 控制输入区与文本的编码格式，支持 `hex` / `hsb` / `rgb`。

### format.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 format demo：编码格式（HEX / HSB / RGB）。
//
// ⚠️ **一处 demo 级替换**：上游用 `useState` + `React.useMemo` 计算展示串；本仓用
//    `ref` + `computed`（同形）。`value` / `format` 走 `v-model:value` / `v-model:format`
//    的受控通道（C11 的双发）。
import type { ColorFormatType, ColorPickerColor } from '@apollo-design/ui';
import { ColorPicker, Space } from '@apollo-design/ui';
import { computed, ref } from 'vue';

/** 上游 `Color`（= `AggregationColor`）：ui barrel 未导出该别名，从 `change` 的载荷反推。 */
type Color = ColorPickerColor;

// ---- HEX ----
const colorHex = ref<Color | string>('#1677ff');
const formatHex = ref<ColorFormatType | undefined>('hex');
const hexString = computed(() =>
  typeof colorHex.value === 'string' ? colorHex.value : colorHex.value.toHexString(),
);

// ---- HSB ----
const colorHsb = ref<Color | string>('hsb(215, 91%, 100%)');
const formatHsb = ref<ColorFormatType | undefined>('hsb');
const hsbString = computed(() =>
  typeof colorHsb.value === 'string' ? colorHsb.value : colorHsb.value.toHsbString(),
);

// ---- RGB ----
const colorRgb = ref<Color | string>('rgb(22, 119, 255)');
const formatRgb = ref<ColorFormatType | undefined>('rgb');
const rgbString = computed(() =>
  typeof colorRgb.value === 'string' ? colorRgb.value : colorRgb.value.toRgbString(),
);
</script>

<template>
  <Space vertical size="medium" :style="{ display: 'flex' }">
    <Space>
      <ColorPicker v-model:value="colorHex" v-model:format="formatHex" />
      <span>HEX: {{ hexString }}</span>
    </Space>
    <Space>
      <ColorPicker v-model:value="colorHsb" v-model:format="formatHsb" />
      <span>HSB: {{ hsbString }}</span>
    </Space>
    <Space>
      <ColorPicker v-model:value="colorRgb" v-model:format="formatRgb" />
      <span>RGB: {{ rgbString }}</span>
    </Space>
  </Space>
</template>
```

## 预设颜色 (presets)

`presets` 传入分组预设色，面板底部会出现对应色块列表。

### presets.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 presets demo：预设颜色分组。
//
// ⚠️ **两处 demo 级替换**（不是能力缺口）：
//   1. 上游用 `theme.useToken()` 取 `colorPrimary` —— 本仓是**零运行时**架构，没有这个
//      hook ⇒ 写**等值字面量** `#1677ff`（默认主题的 `colorPrimary` 解析值）。
//   2. 上游用 `@ant-design/colors` 的 `generate` / `red` / `green` —— 本仓没有该依赖
//      ⇒ 把对应色板**固化成字面量**（值来自 `@ant-design/colors@8.0.1`，逐位一致）。
import type { PresetsItem } from '@apollo-design/ui';
import { ColorPicker } from '@apollo-design/ui';

/** `generate('#1677ff')`（`token.colorPrimary` 的默认值）的 10 档色板。 */
const PRIMARY_PALETTE = [
  '#e6f4ff',
  '#bae0ff',
  '#91caff',
  '#69b1ff',
  '#4096ff',
  '#1677ff',
  '#0958d9',
  '#003eb3',
  '#002c8c',
  '#001d66',
];

/** `@ant-design/colors` 的 `red`。 */
const RED_PALETTE = [
  '#fff1f0',
  '#ffccc7',
  '#ffa39e',
  '#ff7875',
  '#ff4d4f',
  '#f5222d',
  '#cf1322',
  '#a8071a',
  '#820014',
  '#5c0011',
];

/** `@ant-design/colors` 的 `green`。 */
const GREEN_PALETTE = [
  '#f6ffed',
  '#d9f7be',
  '#b7eb8f',
  '#95de64',
  '#73d13d',
  '#52c41a',
  '#389e0d',
  '#237804',
  '#135200',
  '#092b00',
];

/** 上游 `genPresets`：把色板表折成 `{ label, colors, key }` 数组。 */
const genPresets = (palettes: Record<string, string[]>): PresetsItem[] =>
  Object.entries(palettes).map(([label, colors]) => ({ label, colors, key: label }));

const presets = genPresets({ primary: PRIMARY_PALETTE, red: RED_PALETTE, green: GREEN_PALETTE });
</script>

<template>
  <ColorPicker :presets="presets" default-value="#1677ff" />
</template>
```

## 预设渐变色 (presets-line-gradient)

`presets` 的每一项颜色也可以是**渐变**（`mode` 需包含 `gradient`）。

### presets-line-gradient.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 presets-line-gradient demo：预设**渐变色**。
import type { LineGradientType, PresetsItem } from '@apollo-design/ui';
import { ColorPicker } from '@apollo-design/ui';

/** 每项是一组「起点色 / 终点色」。显式元组类型 ⇒ 解构出的两端不是 `undefined`。 */
const PRESET_COLORS: [string, string][] = [
  ['rgb(42, 188, 191)', 'rgb(56, 54, 221)'],
  ['rgb(34, 73, 254)', 'rgb(199, 74, 168)'],
  ['rgb(255, 111, 4)', 'rgb(243, 48, 171)'],
  ['rgb(244, 170, 6)', 'rgb(229, 70, 49)'],
];

const presets: PresetsItem[] = [
  {
    label: 'Liner',
    colors: PRESET_COLORS.map(
      ([start, end]): LineGradientType => [
        { color: start, percent: 0 },
        { color: end, percent: 100 },
      ],
    ),
    defaultOpen: true,
  },
];
</script>

<template>
  <ColorPicker :mode="['single', 'gradient']" :presets="presets" />
</template>
```

## 自定义面板 (panel-render)

使用 #panelRender 定制布局；panel 是稳定的 Vue 组件引用，可直接用 <component :is="panel" />，extra 提供 Picker / Presets 子面板。

### panel-render.vue

```vue
<script setup lang="ts">
// Custom panels use Vue scoped slots and stable component references.
import type { PresetsItem } from '@apollo-design/ui';
import { Col, ColorPicker, Divider, Row, Space } from '@apollo-design/ui';

/** `token.colorPrimary` 的等值字面量。 */
const COLOR_PRIMARY = '#1677ff';

/** `generate('#1677ff')` 的 10 档色板。 */
const PRIMARY_PALETTE = [
  '#e6f4ff',
  '#bae0ff',
  '#91caff',
  '#69b1ff',
  '#4096ff',
  '#1677ff',
  '#0958d9',
  '#003eb3',
  '#002c8c',
  '#001d66',
];
/** `@ant-design/colors` 的 `red`。 */
const RED_PALETTE = [
  '#fff1f0',
  '#ffccc7',
  '#ffa39e',
  '#ff7875',
  '#ff4d4f',
  '#f5222d',
  '#cf1322',
  '#a8071a',
  '#820014',
  '#5c0011',
];
/** `@ant-design/colors` 的 `green`。 */
const GREEN_PALETTE = [
  '#f6ffed',
  '#d9f7be',
  '#b7eb8f',
  '#95de64',
  '#73d13d',
  '#52c41a',
  '#389e0d',
  '#237804',
  '#135200',
  '#092b00',
];
/** `@ant-design/colors` 的 `cyan`。 */
const CYAN_PALETTE = [
  '#e6fffb',
  '#b5f5ec',
  '#87e8de',
  '#5cdbd3',
  '#36cfc9',
  '#13c2c2',
  '#08979c',
  '#006d75',
  '#00474f',
  '#002329',
];

/** 上游 `genPresets`：把色板表折成 `{ label, colors, key }` 数组。 */
const genPresets = (palettes: Record<string, string[]>): PresetsItem[] =>
  Object.entries(palettes).map(([label, colors]) => ({ label, colors, key: label }));

const presets = genPresets({
  primary: PRIMARY_PALETTE,
  red: RED_PALETTE,
  green: GREEN_PALETTE,
  cyan: CYAN_PALETTE,
});
</script>

<template>
  <Space vertical>
    <Space>
      <span>Add title:</span>
      <ColorPicker default-value="#1677ff">
        <template #panelRender="{ panel }">
          <section class="custom-panel">
            <div :style="{ fontSize: '12px', color: 'var(--apollo-color-text)', lineHeight: '20px', marginBottom: '8px' }">Color Picker</div>
            <component :is="panel" />
          </section>
        </template>
      </ColorPicker>
    </Space>
    <Space>
      <span>Horizontal layout:</span>
      <ColorPicker :default-value="COLOR_PRIMARY" :styles="{ popupOverlayInner: { width: '480px' } }" :presets="presets">
        <template #panelRender="{ extra }">
          <Row justify="space-between" :wrap="false">
            <Col :span="12"><component :is="extra.components.Presets" /></Col>
            <Divider vertical :style="{ height: 'auto' }" />
            <Col flex="auto"><component :is="extra.components.Picker" /></Col>
          </Row>
        </template>
      </ColorPicker>
    </Space>
  </Space>
</template>
```

## 自定义语义结构的样式和类 (style-class)

`classNames` / `styles` 可传对象或函数，用来定制 5 个语义槽的类名与样式。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo：`classNames` / `styles` 的**对象 / 函数**两种形态。
//
// ⚠️ **一处 demo 级替换**：上游用 `antd-style` 的 `createStyles`（第三方 CSS-in-JS）生成
//    类名 —— 本仓是**零运行时**架构，没有 CSS-in-JS ⇒ 用 SFC 的 `<style>` 块定义同名类名
//    （效果等价：`classNames.root` 拿到一个带 `border-radius` 的类）。`token.borderRadius`
//    的默认解析值是 `6px`。
import type { ColorPickerProps } from '@apollo-design/ui';
import { ColorPicker, Flex, Space } from '@apollo-design/ui';

/** 上游 `useStyles()` 的产物：`styles.root` 是一个生成的类名。 */
const classNames = { root: 'demo-color-picker-root' };

/** 对象形态：`styles.popup.root` 直接给值。 */
const stylesObject: ColorPickerProps['styles'] = {
  popup: {
    root: {
      border: '1px solid #fff',
    },
  },
};

/**
 * 函数形态：按 `info.props.size` 决定返回什么。
 * ⚠️ 上游这里 `return {}`（不是 `undefined`）—— 本仓 `ColorPickerSemanticValue` 的函数分支
 *    要求返回 `T`（与上游 `GenerateSemantic` 同形），空对象 = 不加任何样式，效果等价。
 */
const stylesFn: ColorPickerProps['styles'] = (info) => {
  if (info.props.size === 'large') {
    return {
      popup: {
        root: {
          border: '1px solid #722ed1',
        },
      },
    };
  }
  return {};
};
</script>

<template>
  <Space :size="[8, 16]" wrap>
    <Flex gap="small">
      <ColorPicker
        default-value="#1677ff"
        :arrow="false"
        :styles="stylesObject"
        :class-names="classNames"
      />
    </Flex>
    <Flex gap="small">
      <ColorPicker
        default-value="#722ed1"
        size="large"
        :styles="stylesFn"
        :arrow="false"
        :class-names="classNames"
      />
    </Flex>
  </Space>
</template>

<style>
.demo-color-picker-root {
  border-radius: 6px;
}
</style>
```

## Pure Render (pure-panel)

静态展示实际面板；原生 attrs 作用于展示宿主，变化通过 Vue 事件通知。

### pure-panel.vue

```vue
<script setup lang="ts">
import type { ColorValueType } from '@apollo-design/ui';
import { ColorPickerPurePanel } from '@apollo-design/ui';
import { ref } from 'vue';

const color = ref<ColorValueType>('#1677ff');
</script>

<template>
  <div>
    <ColorPickerPurePanel :color-picker-props="{ value: color }" @change="value => color = value" />
  </div>
</template>
```

---

# ConfigProvider

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/config-provider


为应用或特性子树提供当前主题、语言、尺寸、禁用、方向和组件默认配置。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/config-provider/demo)：前缀、语言、组件配置、尺寸与禁用、主题、动态尺寸、方向和 `useConfig`，共 8 个示例。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| scopeTag | 可选的原生作用域宿主；省略时不增加包装节点。选择符合 HTML / SVG 内容模型的标签 | `ConfigProviderScopeTag` | — |
| prefixCls | 组件 DOM 类名前缀；自定义前缀需配套静态 CSS | `string` | `'apollo'` |
| iconPrefixCls | 图标前缀，独立于组件前缀 | `string` | `'apollo-icon'` |
| getPopupContainer | 浮层容器；函数随配置更新读取 | `(trigger?: HTMLElement) => HTMLElement \| ShadowRoot` | — |
| getTargetContainer | Affix / Anchor 等滚动感知组件的目标解析器 | `() => HTMLElement \| Window` | — |
| renderEmpty | 空状态内容工厂；返回 `null`、`undefined`、`false` 或空字符串可有意留空 | `RenderEmptyHandler`，返回 `VNodeChild` | 各消费者的默认空状态 |
| locale | 当前语言包；替换、深更新及撤回不会重挂业务内容 | `Locale` | 继承，分片缺失时回退英文 |
| componentSize | 控件默认尺寸；组件自己的 `size` 优先 | `'small' \| 'medium' \| 'middle' \| 'large'` | 继承 |
| componentDisabled | 默认禁用；子级或组件显式 `false` 可覆盖父级 `true` | `boolean` | `false` |
| direction | 布局方向 | `'ltr' \| 'rtl'` | 继承 |
| virtual | 支持虚拟滚动的消费者的默认开关 | `boolean` | `true` |
| variant | 输入、选择和表单控件的默认形态 | `'outlined' \| 'borderless' \| 'filled' \| 'underlined'` | 继承 |
| popupMatchSelectWidth | Select / TreeSelect / Cascader 等的浮层宽度默认值；局部配置优先 | `boolean` | 消费者默认值 |
| theme | 主题预设、明暗模式、用户/组件令牌、算法及 CSS 变量前缀 | `ConfigProviderThemeConfig` | 继承 |
| warning | 开发告警行为；`strict: false` 聚合弃用告警 | `{ strict?: boolean }` | `{}` |
| components | 按各组件契约声明的默认配置，以消费者名称为键；不会自动应用任意组件 prop | `Record<string, ComponentConfigLike>` | — |
| divider | Divider 的精确配置别名 | `DividerConfig` | — |
| empty | Empty 的精确配置别名 | `EmptyConfig` | — |
| spin | Spin 的精确配置别名 | `SpinConfig` | — |
| form | 已接入 Form 的默认配置，含校验消息、必填标记、冒号、标签及语义样式等 | `FormConfig` | — |

### 继承与内容

本层 `undefined` 回落到父级；撤回先前设置的值也会回落。`components` 按组件名合并，同名组件配置整体替换；`divider` / `empty` / `spin` / `form` 精确别名覆盖同名 map 项，组件自己的显式 prop 最优先。

`theme.token` 按键合并，`theme.components` 按组件名和令牌键合并；`inherit: false` 重置父级令牌和组件令牌，保留外层 CSS 变量前缀。表单校验消息按默认数据、父 FormProvider、本地语言和当前有效 form 配置合并；`components.form.validateMessages` 与 `form.validateMessages` 共用同一通道。

`theme.preset` 接受公开 `ThemePreset` 对象；内置预设分别从 `@apollo-design/theme/presets/default`、`mono`、`material3` 导入。`mode` 为 light/dark/system，与预设独立。预设基础配置及当前明暗配置先合并，用户 Seed 再进入算法，用户 Alias 和组件令牌保持最终优先。局部显式 algorithm 保留其原有完整链并替代继承 mode；局部 mode 替代继承 algorithm。此组件默认继承原始配置；基础包的 `ThemeProvider` 保留显式空主题重置，需 `inherit:true` 才继承。活跃 Provider 在 mounted 后跟随系统偏好并释放监听，SSR 的 system 默认亮色。完整变量由当前 Provider 投影，不必为 Mono 加载默认 `tokens.css`；UI 结构样式仍需引入。

默认插槽接收完整 Vue 内容，支持条件内容和多根。没有业务 emits、v-model 或 expose。默认无宿主时 Provider 的 `class` / `style` / `id` / 原生监听器等 attrs 不落到子节点；显式设置 `scopeTag` 时 attrs 落到该原生宿主，原生 style 优先于主题变量。`scopeTag` 是结构选择，改变标签遵循 Vue 原生根替换语义；切换 theme / locale 等配置不会改变内容的逻辑树。

### 主题、SSR 与样式

默认保持 renderless，主题变量在客户端投射到实际原生根，包括动态根和 Portal 内容；不会移动或重建业务节点。原生根自己的 CSS 变量声明优先，卸载或撤回时释放自己的写入并恢复原值。

SSR 会在直接原生槽根上序列化当前 Alias 变量。无法从外部自动给不透传 attrs 的 opaque 组件或纯文本建立服务端 CSS 作用域；需要完整首帧样式时，显式提供符合内容模型的宿主，例如 `<ConfigProvider scope-tag="section" :theme="theme">`。表格可用 `<table><ConfigProvider scope-tag="tbody"><tr>…</tr></ConfigProvider></table>`；默认无宿主也可以安全地位于既有 tbody、ul、select 或 SVG 内。水合时使用相同配置和内容。

静态 CSS 通过变量响应主题，不在运行时生成选择器。发布 CSS 默认只有 `apollo` 前缀；本页前缀 Demo 单独引入了构建期生成的 `brand` CSS。`theme.cssVarPrefix` 改变变量名，需要消费者样式使用相同名字。组件令牌由相应消费者写入和使用，不等于全库所有任意键均有视觉效果。

### 废弃属性

| 旧名 | 新名 |
|---|---|
| autoInsertSpaceInButton | components.button.autoInsertSpace |
| dropdownMatchSelectWidth | popupMatchSelectWidth |

### 静态方法与 composable

| 名称 | 说明 |
|---|---|
| ConfigProvider.ConfigContext | `InjectionKey<ConfigContextValue>`，可用于 `inject`；常规读取使用 `useConfigContext()` |
| ConfigProvider.config / setGlobalConfig | 模块级设置器，传 `{ prefixCls?, iconPrefixCls?, theme? }`，返回 `void`；静态 Modal 等按其消费链读取，不能替代应用内响应式 props |
| ConfigProvider.useConfig / useConfig | 返回 `componentDisabled`、`componentSize` 两个 ComputedRef |
| useDirection / useThemeConfig | 当前方向 / 主题配置的 ComputedRef；无活跃主题源时后者为 `undefined` |
| useComponentConfig(name) | 当前组件配置的惰性视图，在 render / computed 中读取；setup 解构原始值会保存快照 |

`@apollo-design/locale` 的 `useLocale(name)` 统一返回 `[ComputedRef<分片>, ComputedRef<语言码>]`，脚本中读 `.value`，模板会解包。主题包 `useTheme().config` 是可深写的实例 Ref：赋值替换当前有效配置，深写不修改父级或 props；外部主题源变化时重新以外部配置为准。

当前开发版移除了没有消费者的 `csp`、`wave`、`popupOverflow` 和 `theme.prefixCls`，以及旧 `useLocaleReactive` 双通道；见[集中迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/config-provider-contracts.md)。

最近的显式 `ThemeProvider` 也属于当前主题来源，包括空配置 `{}` 的默认主题重置。嵌套 `ConfigProvider` 会在所属原生根投影该来源；没有显式来源时保留纯 CSS 变量继承。


## 前缀 (prefix-cls)

默认类名前缀是 apollo，发布 CSS 仅包含该前缀。设置自定义前缀会更新 DOM 名称；样式需要构建期生成。

本示例的 prefix-cls.css 预先由 genComponentCss('empty', 'brand') 生成，作为静态文件引入。运行时只切换类名，不生成样式表。图标前缀独立由 iconPrefixCls 控制。

### prefix-cls.vue

```vue
<script setup lang="ts">
import { ConfigProvider, Empty } from '@apollo-design/ui';
</script>

<template>
  <ConfigProvider prefix-cls="brand">
    <Empty description="brand-empty：本示例单独加载了对应静态 CSS" />
  </ConfigProvider>
</template>

<style src="./prefix-cls.css"></style>
```

## 语言包 (locale)

`locale` 的替换、深更新和撤回保留业务节点。示例在 Empty 与 Pagination 上显示当前语言，同时保留输入草稿。

`useLocale(name)` 返回两个 ComputedRef，脚本用 `.value`。没有 Provider 时语言码为 undefined；分片浅合并，缺失字段回退 en_US。global.clear 在 en_US / zh_CN 有 Apollo 文案，其它语言沿用默认回退。

### locale.vue

```vue
<script setup lang="ts">
import { en_US, zh_CN } from '@apollo-design/locale';
import { computed, ref } from 'vue';
import { ConfigProvider, Empty, Input, Pagination, Select, Space } from '@apollo-design/ui';

const language = ref<'en' | 'zh'>('zh');
const locale = computed(() => (language.value === 'zh' ? zh_CN : en_US));
const options = [
  { value: 'zh', label: '中文' },
  { value: 'en', label: 'English' },
];
function changeLanguage(value: unknown) {
  if (value === 'en' || value === 'zh') language.value = value;
}
</script>

<template>
  <div>
    <Space wrap style="margin-bottom: 16px">
      <span>locale</span>
      <Select :value="language" :options="options" aria-label="切换示例语言" style="width: 140px" @change="changeLanguage" />
    </Space>
    <ConfigProvider :locale="locale">
      <Input aria-label="切换语言时保留的草稿" placeholder="切换语言后草稿与焦点保持" style="width: 280px" />
      <Empty />
      <Pagination :total="80" :show-size-changer="true" />
    </ConfigProvider>
  </div>
</template>
```

## 组件级配置 (component-config)

精确别名 empty / divider / spin / form 与 components map 共用当前配置链。map 的键和字段以各组件支持的配置为准，不等于自动应用全部组件 props。

嵌套时不同组件名继承，同名配置整体替换；直接别名优先于同名 map 项，组件自身显式 props 最优先。示例同时展示 Empty / Divider 的语义样式与 components.button.shape。

### component-config.vue

```vue
<script setup lang="ts">
/**
 * Direct aliases and the open component configuration map share one consumer path.
 *
 * `empty` / `divider` / `spin` / `form` have precise aliases. Other component defaults
 * use the keys documented by their consumer, such as components.button.shape.
 *
 * 合并规则：组件自己的 prop **优先于** ConfigProvider 的配置。
 */
import { Button, ConfigProvider, Divider, Empty } from '@apollo-design/ui';
</script>

<template>
  <ConfigProvider
    :empty="{
      className: 'cp-empty',
      classNames: { description: 'cp-empty-description' },
      styles: { image: { opacity: 0.6 } },
    }"
    :divider="{ className: 'cp-divider' }"
    :components="{ button: { shape: 'round' } }"
  >
    <Empty description="Provider 配置了插画与描述的样式" />
    <Divider />
    <Button>圆角默认配置</Button>
  </ConfigProvider>
</template>
```

## 尺寸与全局禁用 (size-disabled)

`componentSize` 与 `componentDisabled` 是**两条独立的 context**（与 antd 同），
下游用 `useSize()` / `useDisabled()` / `useConfig()` 读取。

两条判据**不同**，不能统一（这是最容易写错的地方）：

| 开关 | 判据 | 为什么 |
|---|---|---|
| `componentSize` | `componentSize \|\| 父级` | 未设置就继承 |
| `componentDisabled` | `componentDisabled ?? 父级` | `false` 必须能**显式关闭**父级的 `true` |

⚠️ 返回值是 `ComputedRef`（要 `.value`），不是 antd 那样的裸值 ——
裸值在 Vue 里等于把配置在 setup 期定死（差异 D27）。

### size-disabled.vue

```vue
<script setup lang="ts">
/**
 * `componentSize` / `componentDisabled` —— 两个**独立** context。
 *
 * 下游组件用 `useSize(() => props.size)` / `useDisabled(() => props.disabled)` 读取，
 * 或者用 `useConfig()` 一次拿两个。
 *
 * ⚠️ 探针必须挂在 `ConfigProvider` **内部**：`inject` 只沿父链解析，
 *    写在同一个 setup 里是拿不到的（PITFALLS 37）。
 */
import { h } from 'vue';
import { Button, ConfigProvider, Input, Space, useConfig } from '@apollo-design/ui';

const Child = {
  name: 'AUseConfigChild',
  setup() {
    const { componentSize, componentDisabled } = useConfig();
    return () =>
      h('div', null, [
        h('div', null, `componentSize：${componentSize.value ?? '（未设置）'}`),
        h('div', null, `componentDisabled：${String(componentDisabled.value)}`),
        h(Space, { wrap: true, style: { marginTop: '12px' } }, () => [
          h(Input, { 'aria-label': '全局禁用输入框', placeholder: '继承 large 与 disabled' }),
          h(Button, null, () => '已禁用按钮'),
        ]),
      ]);
  },
};
</script>

<template>
  <ConfigProvider component-size="large" :component-disabled="true">
    <Child />
  </ConfigProvider>
</template>
```

## 主题 (theme)

theme 支持 token、algorithm（单个或数组）、components、cssVarPrefix 和 inherit。示例使用显式 section 宿主，让完整内容与 Alias 变量在 SSR 同树；原生宿主 attrs/style 按原生规则合并。

默认无宿主时客户端向实际原生根投射变量，SSR 直接原生槽根可序列化；opaque 组件或纯文本需要显式宿主才能获得完整服务端 CSS 作用域。算法切换与 useTheme().config 可写 Ref 保留业务草稿，外部主题变更会恢复外部配置。组件令牌由各组件消费者落地，不在运行时生成 CSS 选择器。

### theme.vue

```vue
<script setup lang="ts">
import { compactAlgorithm, darkAlgorithm, useTheme } from '@apollo-design/theme';
import type { ConfigProviderThemeConfig } from '@apollo-design/ui';
import { computed, defineComponent, Fragment, h, ref } from 'vue';
import { Button, ConfigProvider, Input, Select, Space } from '@apollo-design/ui';

const mode = ref<'default' | 'dark' | 'compact' | 'both'>('default');
const modes = [
  { value: 'default', label: '继承外层算法' },
  { value: 'dark', label: '暗色' },
  { value: 'compact', label: '紧凑' },
  { value: 'both', label: '暗色 + 紧凑' },
];
function changeMode(value: unknown) {
  if (value === 'default' || value === 'dark' || value === 'compact' || value === 'both')
    mode.value = value;
}
const theme = computed<ConfigProviderThemeConfig>(() => ({
  token: { colorPrimary: '#006d75' },
  ...(mode.value === 'default'
    ? {}
    : {
        algorithm:
          mode.value === 'dark'
            ? darkAlgorithm
            : mode.value === 'compact'
              ? compactAlgorithm
              : [darkAlgorithm, compactAlgorithm],
      }),
}));
const RuntimeFont = defineComponent({
  setup() {
    const context = useTheme();
    function increase() {
      context.config.value = {
        ...context.config.value,
        token: {
          ...context.config.value.token,
          fontSize: Math.min(24, context.token.value.fontSize + 1),
        },
      };
    }
    return () =>
      h(Fragment, [
        h(Button, { onClick: increase }, () => '运行时字体 +1'),
        h(
          'output',
          { style: { marginInlineStart: '8px' } },
          `fontSize: ${context.token.value.fontSize}`,
        ),
      ]);
  },
});
</script>

<template>
  <div>
    <Space wrap style="margin-bottom: 16px">
      <span>theme.algorithm</span>
      <Select :value="mode" :options="modes" aria-label="主题算法" style="width: 200px" @change="changeMode" />
    </Space>
    <ConfigProvider scope-tag="section" :theme="theme" class="theme-demo-scope" style="display: block">
      <Space wrap>
        <div class="theme-demo-color" aria-label="当前主题主色" role="img" />
        <Input aria-label="主题切换时保留的草稿" placeholder="算法切换保留草稿" style="width: 220px" />
        <RuntimeFont />
      </Space>
    </ConfigProvider>
  </div>
</template>

<style scoped>
.theme-demo-scope {
  display: block;
  padding: 16px;
  border: 1px solid var(--apollo-color-border);
  border-radius: var(--apollo-border-radius-lg);
  background: var(--apollo-color-bg-container);
  color: var(--apollo-color-text);
}
.theme-demo-color {
  width: 40px;
  height: 40px;
  border-radius: var(--apollo-border-radius);
  background: var(--apollo-color-primary);
}
</style>
```

## 布局方向 (direction)

通过 `direction` 切换整棵子树的 LTR / RTL 排列方向，输入框、按钮与间距会同步响应。

### direction.vue

```vue
<script setup lang="ts">
import type { DirectionType } from '@apollo-design/ui';
import { Button, ConfigProvider, Input, Select, Space, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const direction = ref<DirectionType>('ltr');

const directionOptions = [
  { value: 'ltr', label: 'LTR（从左到右）' },
  { value: 'rtl', label: 'RTL（从右到左）' },
];

function onDirectionChange(value: unknown): void {
  if (value === 'ltr' || value === 'rtl') direction.value = value;
}
</script>

<template>
  <div>
    <Space wrap :size="12" style="margin-bottom: 16px">
      <span>direction</span>
      <Select
        aria-label="文字方向"
        :value="direction"
        :options="directionOptions"
        style="width: 200px"
        @change="onDirectionChange"
      />
      <Tag color="blue">{{ direction }}</Tag>
    </Space>

    <ConfigProvider :direction="direction">
      <div class="direction-demo-panel">
        <Space wrap>
          <Input aria-label="姓名" placeholder="请输入姓名" style="width: 180px" />
          <Button>提交</Button>
          <Button>取消</Button>
        </Space>
        <p class="direction-demo-hint">
          子树内的输入框、按钮与间距都由 ConfigProvider 的 direction 属性控制排列方向。
        </p>
      </div>
    </ConfigProvider>
  </div>
</template>

<style scoped>
.direction-demo-panel {
  padding: 16px;
  border: 1px solid var(--apollo-color-border);
  border-radius: var(--apollo-border-radius-lg);
  background: var(--apollo-color-fill-quaternary);
}

.direction-demo-hint {
  margin: 12px 0 0;
  color: var(--apollo-color-text-secondary);
}
</style>
```

## 组件尺寸 (component-size)

使用 `componentSize` 统一设置子树内 Input、Button 等组件的尺寸，下拉框可实时切换 small / middle / large。

### component-size.vue

```vue
<script setup lang="ts">
import type { SizeType } from '@apollo-design/ui';
import { Button, ConfigProvider, Input, Select, Space, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const componentSize = ref<SizeType>('middle');

const sizeOptions: { value: SizeType; label: string }[] = [
  { value: 'small', label: 'small' },
  { value: 'middle', label: 'middle' },
  { value: 'large', label: 'large' },
];

function onSizeChange(value: unknown): void {
  if (value === 'small' || value === 'medium' || value === 'middle' || value === 'large') {
    componentSize.value = value;
  }
}
</script>

<template>
  <div>
    <Space wrap :size="12" style="margin-bottom: 16px">
      <span>componentSize</span>
      <Select
        aria-label="组件尺寸"
        :value="componentSize"
        :options="sizeOptions"
        style="width: 160px"
        @change="onSizeChange"
      />
      <Tag color="blue">{{ componentSize }}</Tag>
    </Space>

    <ConfigProvider :component-size="componentSize">
      <div class="component-size-demo-panel">
        <Space wrap>
          <Input aria-label="组件尺寸输入框" placeholder="组件尺寸跟随配置" style="width: 220px" />
          <Button>操作按钮</Button>
          <Button>次要按钮</Button>
        </Space>
        <p class="component-size-demo-hint">
          未显式声明 size 的 Input 与 Button 会从 ConfigProvider 的 componentSize 继承尺寸。
        </p>
      </div>
    </ConfigProvider>
  </div>
</template>

<style scoped>
.component-size-demo-panel {
  padding: 16px;
  border: 1px solid var(--apollo-color-border);
  border-radius: var(--apollo-border-radius-lg);
  background: var(--apollo-color-fill-quaternary);
}

.component-size-demo-hint {
  margin: 12px 0 0;
  color: var(--apollo-color-text-secondary);
}
</style>
```

## 读取配置 (use-config)

在 ConfigProvider 内部调用 `useConfig()` 读取 `componentSize` 与 `componentDisabled`，并用外部下拉框和开关实时验证上下文同步。

### use-config.vue

```vue
<script setup lang="ts">
import type { SizeType } from '@apollo-design/ui';
import {
  Button,
  ConfigProvider,
  Input,
  Select,
  Space,
  Switch,
  Tag,
  useConfig,
} from '@apollo-design/ui';
import { h, ref } from 'vue';

const componentSize = ref<SizeType>('middle');
const componentDisabled = ref(false);

const sizeOptions: { value: SizeType; label: string }[] = [
  { value: 'small', label: 'small' },
  { value: 'middle', label: 'middle' },
  { value: 'large', label: 'large' },
];

function onSizeChange(value: unknown): void {
  if (value === 'small' || value === 'medium' || value === 'middle' || value === 'large') {
    componentSize.value = value;
  }
}

/**
 * 探针必须定义在 ConfigProvider 内部：inject 只沿父链解析。
 * 用渲染函数读取 useConfig() 返回的 ComputedRef，配置变化时探针会同步刷新。
 */
const ConfigProbe = {
  name: 'AUseConfigProbe',
  setup() {
    const { componentSize: size, componentDisabled: disabled } = useConfig();

    return () =>
      h('div', { class: 'use-config-demo-probe' }, [
        h('div', { class: 'use-config-demo-values' }, [
          h('span', null, 'useConfig() 读取到：'),
          h(Tag, { color: 'blue' }, () => `componentSize: ${size.value ?? 'undefined'}`),
          h(
            Tag,
            { color: disabled.value ? 'red' : 'green' },
            () => `componentDisabled: ${String(disabled.value)}`,
          ),
        ]),
        h(Space, { wrap: true, style: { marginTop: '12px' } }, () => [
          h(Input, {
            'aria-label': '尺寸与禁用状态示例',
            placeholder: '尺寸与禁用状态跟随配置',
            style: { width: '240px', maxWidth: '100%' },
          }),
          h(Button, null, () => '提交'),
          h(Button, null, () => '取消'),
        ]),
      ]);
  },
};
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>componentSize</span>
      <Select
        aria-label="组件尺寸"
        :value="componentSize"
        :options="sizeOptions"
        style="width: 140px"
        @change="onSizeChange"
      />
      <span>componentDisabled</span>
      <Switch v-model:checked="componentDisabled" aria-label="禁用全部组件" />
      <Tag color="blue">{{ componentDisabled ? '全局禁用' : '正常可用' }}</Tag>
    </Space>

    <ConfigProvider :component-size="componentSize" :component-disabled="componentDisabled">
      <ConfigProbe />
    </ConfigProvider>
  </div>
</template>

<style>
.use-config-demo-probe {
  padding: 16px;
  border: 1px solid var(--apollo-color-border);
  border-radius: var(--apollo-border-radius-lg);
  background: var(--apollo-color-fill-quaternary);
}

.use-config-demo-values {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 8px;
}
</style>
```

---

# DatePicker

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/date-picker


> 2026-10-30 当前 API：动态内容使用 `#cellRender="{ current, info }"`、`#panelRender="{ originPanel }"`、`#extraFooter="{ mode }"`、`#tagRender="scope"`；前缀、后缀、清除、区间分隔与预设分别使用同名具名槽。移除旧函数渲染 props、`addon`、无实际组件的 PurePanel 类型及 notification props；使用 `@select`/其它原生 emits。`@keydown` 只收到原生 KeyboardEvent，可直接 preventDefault()；支持 `v-model:mode`。只读输入按 ArrowDown 进入面板，方向键导航，Enter/Space 选值，Escape 返回。DOM refs 在挂载前/卸载后为 null。

# DatePicker 日期选择器

输入或选择日期的控件。

视口宽度为 575px 及以下时，日期时间与区间的面板在视口内换行展示，保留全部日期格、时间列与确认操作；两个区间面板均可通过原生键盘选值。较宽视口继续并排展示。

## 何时使用

- 当用户需要输入一个日期，可以点击标准输入框，弹出日期面板进行选择；
- 需要在「日期 / 周 / 月 / 季度 / 年 / 时间」等粒度间切换时，用 `picker` 指定；
- 需要选择一段时间范围时，用 `RangePicker`。

## 引入

```ts
import { DatePicker, RangePicker } from '@apollo-design/ui';
```

## 代码演示



<!-- 代码演示由 `demo/*.md`（标题 / 顺序 / 说明）+ `demo/*.vue` 自动收录。
     当前覆盖：基本、范围、禁用日期、上下界、日期时间、12 小时制与步长、预设范围、
     受控、格式化、尺寸/状态/变体、多选、自定义单元格、确认、面板底部、范围时间、
     自定义面板、弹层位置、允许空值。 -->

## API

### 单值 DatePicker

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value（`v-model:value`） | 受控值。`null` 表示「受控且为空」 | `DateType \| DateType[] \| null` | —— |
| defaultValue | 非受控初始值 | 同上 | —— |
| picker | 选择器粒度 | `'time' \| 'date' \| 'week' \| 'month' \| 'quarter' \| 'year'` | `'date'` |
| mode | 面板的**当前视图**粒度（受控时需自己处理 `panelChange`） | `'time' \| 'date' \| 'week' \| 'month' \| 'quarter' \| 'year' \| 'decade'` | —— |
| format | 格式。支持字符串 / 数组（多套解析格式）/ 掩码对象 / **函数** | `DatePickerFormat` | 由 `picker` 与语言包推导 |
| showTime | 显示时间选择。`true` 或配置对象（`use12Hours` / `disabledTime` / `hideDisabledOptions` …） | `boolean \| SharedTimeProps` | —— |
| showWeek | 周选择器下显示周数 | `boolean` | —— |
| showToday | 显示「今天」 | `boolean` | `true` |
| showNow | 时间面板显示「此刻」 | `boolean` | `true` |
| open（`v-model:open`） | 受控开合。`undefined` = 非受控 | `boolean` | —— |
| defaultOpen | 非受控初始开合 | `boolean` | `false` |
| needConfirm | 是否要点「确定」才提交。⚠️ **默认值取决于粒度**：`time` / `datetime` 为 `true`，其余 `false` | `boolean` | 见左 |
| multiple | 多选 | `boolean` | `false` |
| order | `multiple` 时按日期排序 | `boolean` | `true` |
| presets | 快捷选项。`value` 支持**函数**（懒求值） | `ValueDate[]` | —— |
| disabledDate | 不可选日期 | `(date, info) => boolean` | —— |
| minDate / maxDate | 可选范围的边界（静态日期，与上游一致） | `DatePickerDate` | —— |
| placeholder | 占位符 | `string` | 由语言包给出 |
| locale | 语言包（与 `ConfigProvider` 的 `locale.DatePicker` 深合并） | `PickerLocale` | —— |
| size | 尺寸（未传走 `ConfigProvider`） | `'small' \| 'medium' \| 'middle' \| 'large'` | —— |
| variant | 形态 | `'outlined' \| 'borderless' \| 'filled' \| 'underlined'` | `'outlined'` |
| status | 校验状态。⚠️ **只加类名，不改 `aria-invalid`** | `'error' \| 'warning'` | —— |
| disabled | 禁用 | `boolean` | `false` |
| inputReadOnly | 输入框只读（禁止键入，只能用面板选） | `boolean` | `false` |
| allowClear | 允许清除。传对象可自定义图标 | `boolean \| { clearIcon }` | `true` |
| suffixIcon | 后缀图标 | `VNodeChild` | 日历图标 |
| prefix | 前缀（可放图标或文字） | `VNodeChild` | —— |
| clearIcon | 清除图标（**deprecated** → `allowClear.clearIcon`） | `VNodeChild` | —— |
| popupClassName | 浮层类名（**deprecated** → `classNames.popup`） | `string` | —— |
| popupStyle | 浮层样式（**deprecated** → `styles.popup`） | `CSSProperties` | —— |
| dropdownClassName | 同 `popupClassName`（**deprecated**） | `string` | —— |
| placement | 浮层落点。未传时按方向取默认（LTR `bottomLeft` / RTL `bottomRight`） | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'` | —— |
| popupAlign | 浮层的对齐偏移 | `AlignType` | —— |
| builtinPlacements | 自定义落点表 | `Record<string, AlignType>` | 内置四个 |
| getPopupContainer | 浮层挂载容器 | `(node) => HTMLElement` | `document.body` |
| transitionName | 浮层动效名 | `string` | `${rootPrefixCls}-slide-up` |
| required | 原生 `required`（透传 `input[required]` 与 `aria-required`） | `boolean` | —— |
| name / autoComplete / id | 绑定原生 `input`；`id` 可与 `label for` 关联 | `string` | `autoComplete: 'off'` |
| tabIndex / tabindex | 原生输入框的 Tab 顺序；`tabindex` 可作为 Vue attr 传入 | `number` | —— |
| autoFocus | 挂载时聚焦第一个未禁用的输入框 | `boolean` | `false` |
| prefixCls | 类名前缀。⚠️ 默认是 **`apollo-picker`**（不是 `apollo-date-picker`） | `string` | —— |
| class / style | **根节点原生 attrs**（替代上游 `className` / `rootClassName` / `style`） | `string \| array \| object` / `CSSProperties` | —— |
| classNames / styles | 语义化类名 / 样式（**4 个平铺 + 7 个嵌套 `popup`**）。`popup` 允许 **string**（= `popup.root`）。`classNames.root` / `styles.root` 落**选择器根元素**（与原生 `class` / `style` 合并，原生胜） | `DatePickerSemanticAllType` | —— |

### 顶层时间配置

上游 `PickerProps extends Omit<SharedTimeProps, 'format' | 'defaultValue'>`（`SinglePicker.d.ts`）⇒
下面这组键是**顶层 prop**（不必塞进 `showTime`），与 `showTime` 在 `getTimeProps` 内部合并
（`showTime` 里的同名键**胜**）。它们对**日期面板**与**时间面板**都生效。

| Prop | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| use12Hours | 12 小时制（时间列多一列上午下午） | `boolean` | —— |
| showHour / showMinute / showSecond / showMillisecond | 显式开关某一列 | `boolean` | 全部按格式推导 |
| hourStep / minuteStep / secondStep / millisecondStep | 列内档位步长 | `number` | `1` / `1` / `1` / `100` |
| hideDisabledOptions | 为真时**跳过**禁用档位（而不是渲染成禁用态） | `boolean` | `false` |
| disabledTime | 按天给出禁用的档位（`disabledHours` 等三个 legacy 键见「兼容性说明」） | `(date) => DisabledTimes` | —— |
| changeOnScroll | 时间列滚动时立即改值 | `boolean` | `false` |
| defaultOpenValue | **无值时面板的锚定时刻**（不写入值；点「确定」才会落值） | `DatePickerDate` | —— |

### 事件

| 事件 | 说明 | 载荷 |
| --- | --- | --- |
| `update:value` | `v-model:value` 通道 | `(date)` |
| `change` | 值变化（与 `update:value` **同时**发） | `(date, dateString)` |
| `calendarChange` | 面板选中过程中每次变化（未提交也发） | `(date, dateString, info)`，`info.range` / `info.from` |
| `ok` | 点「确定」 | `(date)` |
| `openChange` | 浮层开合 | `(open, config?)` |
| `update:open` | `v-model:open` 通道 | `(open)` |
| `pickerValueChange` | 面板浏览值变化 | `(date, info)`，`info.source` 为 `'reset' \| 'panel'` |
| `update:pickerValue` | `v-model:pickerValue` 通道 | `(date)` |
| `panelChange` | 面板粒度变化 | `(value, mode)` |
| `clear` | 点清除按钮 | —— |
| `focus` / `blur` | 焦点进出 | `(event, info)` |
| `invalid` | 键入值非法 | `(invalid)` |
| `submit` | 表单提交 | `(event)` |
| `keydown` | 按键（deprecated `onKeyDown` 的通道） | `(event: KeyboardEvent)` |

### Slots

| 插槽 | 说明 | 参数 |
| --- | --- | --- |
| `panelRender` | 替代 `panelRender` prop | `{ originPanel }` |
| `extraFooter` | 替代 `renderExtraFooter` prop | `{ mode }` |
| `cellRender` | 替代 `cellRender` prop | `{ current, info }` |

### Expose

| 方法 | 说明 | 类型 |
| --- | --- | --- |
| `focus` | 聚焦输入框 | `(options?: FocusOptions) => void` |
| `blur` | 失焦 | `() => void` |
| `nativeElement` | 根节点 | `HTMLDivElement` |

### RangePicker（与单值的差异）

| 参数 | 差异 |
| --- | --- |
| `value` / `defaultValue` | 元组 `[start, end]`。⚠️ **`null` 与 `undefined` 语义不同**：`null` = 「清空该端」，`undefined` = 「尚未选」 |
| `placeholder` | 元组 `[string, string]` |
| `id` | `string \| { start?: string; end?: string }`；字符串只绑定起点，对象分别绑定两端，不生成额外 id |
| `separator` | 两端之间的分隔符。**默认分隔符带 `aria-hidden`；自定义的会去掉它** |
| `allowEmpty` | 允许某一端为空（`boolean` 或两端元组） |
| `disabled` | `boolean` 或两端元组。⚠️ 根类名 `-disabled` 只在**两端都禁**时加 |
| `showTime` | `boolean \| RangeTimeProps`（`disabledTime` 多 `range` / `info` 两个参数） |
| `presets` | `RangeValueDate[]` |
| `onSelect` | **deprecated**，且只在 `picker === 'time'` 时生效 |
| `focus` | 签名不同：`(index?) => void`，可指定聚焦哪一端 |
| `startInput` / `endInput` | 两个原生输入框 |

### 原生属性落点

`class`、`style`、`data-*` 和原生鼠标事件留在选择器根。`id`、`tabIndex` / `tabindex`、`name`、`required`、`autoComplete`、`autoFocus` 以及 `aria-*` 绑定实际输入框；范围选择器的共享属性应用到两端。`aria-invalid` 由内部输入校验维护，`aria-required` 默认随 `required`，可显式覆盖。受控值、输入事件和 ref 由组件维护。

修复 F01 后，原先根上的输入 ARIA 和 Tab 顺序移到 input；请将针对这些属性的 DOM 查询指向 input。范围两端需要不同标签时使用对象 `id` 与两个 `label for`。

## Theme

组件级 Token —— **45 个**，全部落成 CSS 变量 `--apollo-date-picker-*`。

> 下表是 `node tests/visual/debug/extract-date-picker-css.mjs --tokens` 的**实测值**
> （antd 6.6.4 默认主题），不是推算。

| Token | 默认值 |
| --- | --- |
| `activeBg` | `#ffffff` |
| `activeBorderColor` | `#1677ff` |
| `activeShadow` | `0 0 0 2px rgba(5,145,255,0.1)` |
| `addonBg` | `rgba(0,0,0,0.02)` |
| `arrowPath` | `path('M 0 8 A 4 4 0 0 0 2.828…')` |
| `arrowPolygon` | `polygon(1.6568542494923806px 100%, 50% 1.6568542494923806px, …)` |
| `arrowShadowWidth` | `8.970562748477143px` |
| `cellActiveWithRangeBg` | `#e6f4ff` |
| `cellBgDisabled` | `rgba(0,0,0,0.04)` |
| `cellHeight` | `24px` |
| `cellHoverBg` | `rgba(0,0,0,0.04)` |
| `cellHoverWithRangeBg` | `#cbe0fd` |
| `cellRangeBorderColor` | `#82b4f9` |
| `cellWidth` | `36px` |
| `errorActiveShadow` | `0 0 0 2px rgba(255,38,5,0.06)` |
| `hoverBg` | `#ffffff` |
| `hoverBorderColor` | `#4096ff` |
| `inputFontSize` | `14px` |
| `inputFontSizeLG` | `16px` |
| `inputFontSizeSM` | `14px` |
| `lineWidthFocus` | `1px` |
| `multipleItemBg` | `rgba(0,0,0,0.06)` |
| `multipleItemBorderColor` | `transparent` |
| `multipleItemBorderColorDisabled` | `transparent` |
| `multipleItemColorDisabled` | `rgba(0,0,0,0.25)` |
| `multipleItemHeight` | `24px` |
| `multipleItemHeightLG` | `32px` |
| `multipleItemHeightSM` | `16px` |
| `multipleSelectorBgDisabled` | `rgba(0,0,0,0.04)` |
| `paddingBlock` | `4px` |
| `paddingBlockLG` | `7px` |
| `paddingBlockSM` | `0px` |
| `paddingInline` | `11px` |
| `paddingInlineLG` | `11px` |
| `paddingInlineSM` | `7px` |
| `presetsMaxWidth` | `200px` |
| `presetsWidth` | `120px` |
| `textHeight` | `40px` |
| `timeCellHeight` | `28px` |
| `timeColumnHeight` | `224px` |
| `timeColumnWidth` | `56px` |
| `warningActiveShadow` | `0 0 0 2px rgba(255,215,5,0.1)` |
| `withoutTimeCellHeight` | `66px` |
| `zIndexPopup` | `1050` |
| `INTERNAL_FIXED_ITEM_MARGIN` | `2px` —— 变量名是 **`--apollo-date-picker-internal_fixed_item_margin`**（带**下划线**） |

> ⚠️ 另有**一个规则内声明**的变量 `--apollo-date-picker-affix-color`（默认 `inherit`，
> 错误 / 警告态被覆盖）—— 它**不在** `prepareComponentToken` 的返回值里，而是写在
> 样式规则内部。详见 `README §4`。

## 设计说明

### 类名前缀与 CSS 变量命名空间**不同名**

默认类名是 **`apollo-picker`**（上游 `getPrefixCls('picker', …)` 传的是**字面量** `'picker'`），
而 CSS 变量是 **`--apollo-date-picker-*`**（由组件名 `DatePicker` 派生）。
两者不同名是**上游行为**，不是笔误 —— 自定义主题时别改错。

### time-picker 与本组件共用一套样式

`ant-picker` 前缀被 date-picker 与 time-picker 共用（上游刻意如此）⇒ 本组件的样式里
含 time-picker 的规则。那是**对的**（同一组件族）。

### 静态 CSS 的一处已知差异

构建期解析出来的常量（padding 算式、`activeShadow` 模板串、`cellHoverWithRangeBg` 的
`lighten(35)` 等）在**静态 CSS** 里被内联成字面值 ⇒ **不随主色变化**
（上游 cssinjs 会在运行时重算）。这是本仓「静态 CSS + CSS 变量」架构的固有差异，
不是 bug；影响面由 L6 的主题矩阵钉住。


## 基本 (basic)

五种选择粒度（日 / 周 / 月 / 季 / 年）由 `picker` 控制。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo（5 个 picker 形态：date / week / month / quarter / year）。

import type { SingleValue } from '@apollo-design/ui';
import { DatePicker, Flex } from '@apollo-design/ui';

const onChange = (date: SingleValue, dateString: string | string[] | null) => {
  console.log(date, dateString);
};
</script>

<template>
  <Flex gap="small" vertical align="flex-start">
    <DatePicker @change="onChange" />
    <DatePicker picker="week" @change="onChange" />
    <DatePicker picker="month" @change="onChange" />
    <DatePicker picker="quarter" @change="onChange" />
    <DatePicker picker="year" @change="onChange" />
  </Flex>
</template>
```

## 范围选择器 (range-picker)

`DatePicker.RangePicker`（或具名导出的 `RangePicker`）用于选择一个日期范围。

### range-picker.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 range-picker demo（DatePicker.RangePicker 的两种取用方式）。

import type { NoUndefinedRangeValue } from '@apollo-design/ui';
import { DatePicker, Flex, RangePicker } from '@apollo-design/ui';

// ⚠️ 必须按 `RangePickerEmits['change']` 的真实签名写：第一参**可为 `null`**
//    （受控清空），第二参是**定长二元组**（不是 `string | string[] | null`）。
//    此前写成 `(RangeValue, string | string[] | null)` ⇒ 与 emits 不兼容，
//    在 `test:types` 里是一条「unhandled source error」（会让门禁失真）。
const onChange = (value: NoUndefinedRangeValue | null, dateString: [string, string]) => {
  console.log(value, dateString);
};
</script>

<template>
  <Flex gap="small" vertical align="flex-start">
    <DatePicker.RangePicker @change="onChange" />
    <RangePicker @change="onChange" />
  </Flex>
</template>
```

## 禁用日期 (disabled-date)

`disabledDate` 按当前面板粒度拿到日期；示例禁用周六/周日，单值与范围版本都生效。

### disabled-date.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/disabled-date.tsx
import { DatePicker, type DisabledDate, Flex } from '@apollo-design/ui';

/** 禁用周末：disabledDate 返回 true 的日期不可选。 */
const disabledDate: DisabledDate = (current) => current.day() === 0 || current.day() === 6;
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker :disabled-date="disabledDate" placeholder="只能选工作日" />
    <DatePicker.RangePicker :disabled-date="disabledDate" />
  </Flex>
</template>
```

## 上下界 (min-max-date)

`minDate` / `maxDate` 同时限制可选日期与面板导航；越界日期以禁用态呈现。

### min-max-date.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/min-max-date.tsx：可选区间 [今天-7, 今天+7]
import { DatePicker, Flex } from '@apollo-design/ui';
import dayjs from 'dayjs';

const minDate = dayjs().subtract(7, 'day');
const maxDate = dayjs().add(7, 'day');
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker :min-date="minDate" :max-date="maxDate" placeholder="今天前后 7 天" />
    <div class="demo-hint">
      可选范围：{{ minDate.format('YYYY-MM-DD') }} ~ {{ maxDate.format('YYYY-MM-DD') }}
    </div>
  </Flex>
</template>
```

## 日期时间 (show-time)

`show-time` 打开时间面板；`format` 决定输入框与 `change` 第二参的文本格式。

### show-time.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/show-time.tsx
import { DatePicker, Flex, type SingleValue } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<SingleValue>(null);
const text = ref('');

const onChange = (date: SingleValue, dateString: string | string[] | null) => {
  value.value = date;
  text.value = typeof dateString === 'string' ? dateString : '';
};
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker
      v-model:value="value"
      show-time
      format="YYYY-MM-DD HH:mm:ss"
      placeholder="选择日期时间"
      @change="onChange"
    />
    <div class="demo-hint">当前值：{{ text || '（空）' }}</div>
  </Flex>
</template>
```

## 12 小时制与步长 (time-12h)

`use12Hours` 增加上下午列；`hourStep` / `minuteStep` 控制时间列可选项的步长。

### time-12h.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/time.tsx（12 小时制）
import { DatePicker, Flex } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker
      show-time
      use12-hours
      format="YYYY-MM-DD hh:mm:ss A"
      placeholder="12 小时制"
    />
    <DatePicker
      show-time
      :show-hour="true"
      :show-minute="true"
      :show-second="false"
      :hour-step="2"
      :minute-step="15"
      format="YYYY-MM-DD HH:mm"
      placeholder="步长：2 小时 / 15 分钟"
    />
  </Flex>
</template>
```

## 预设范围 (presets)

`presets` 在面板左侧（范围版）提供常用区间；值可以是 dayjs 实例，也可以是返回实例的函数（懒求值）。

### presets.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/presets.tsx
import { DatePicker, type RangeValueDate, type ValueDate } from '@apollo-design/ui';
import dayjs from 'dayjs';

const presets: ValueDate[] = [
  { label: '今天', value: dayjs() },
  { label: '昨天', value: dayjs().subtract(1, 'day') },
  { label: '一周前', value: dayjs().subtract(1, 'week') },
];

const rangePresets: RangeValueDate[] = [
  { label: '最近一周', value: [dayjs().subtract(1, 'week'), dayjs()] },
  { label: '最近一个月', value: [dayjs().subtract(1, 'month'), dayjs()] },
  { label: '本月', value: [dayjs().startOf('month'), dayjs().endOf('month')] },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; align-items: flex-start">
    <DatePicker :presets="presets" placeholder="单值预设" />
    <DatePicker.RangePicker :presets="rangePresets" />
  </div>
</template>
```

## 受控 (controlled)

`v-model:value` 控制值、`v-model:open` 控制面板开合；外部按钮可以直接设值、清空或打开面板。

### controlled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/controlled.tsx（value + open 双受控）
import { Button, DatePicker, Flex, type SingleValue, Space } from '@apollo-design/ui';
import dayjs from 'dayjs';
import { ref } from 'vue';

const value = ref<SingleValue>(null);
const open = ref(false);

const setToday = () => {
  value.value = dayjs();
};
const clear = () => {
  value.value = null;
};
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <Space wrap>
      <DatePicker v-model:value="value" v-model:open="open" placeholder="受控日期" />
      <span class="demo-hint">open = {{ open }}</span>
    </Space>
    <Space wrap>
      <Button size="small" @click="open = true">打开面板</Button>
      <Button size="small" @click="setToday">设为今天</Button>
      <Button size="small" @click="clear">清空</Button>
    </Space>
  </Flex>
</template>
```

## 格式化 (format)

`format` 控制输入框展示与 `dateString`；范围版可传一个格式给两端，或传二元组分别指定。

### format.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/format.tsx
import { DatePicker, Flex } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker format="DD/MM/YYYY" placeholder="DD/MM/YYYY" />
    <DatePicker format="YYYY年MM月DD日" placeholder="YYYY年MM月DD日" />
    <DatePicker.RangePicker
      :format="['YYYY-MM-DD', 'YYYY/MM/DD']"
      :placeholder="['开始日期', '结束日期']"
    />
  </Flex>
</template>
```

## 尺寸、状态与变体 (size-status-variant)

`size` 控制输入框尺寸，`status` 提供 error/warning 状态，`variant` 切换 outlined / filled / borderless / underlined。

### size-status-variant.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/size.tsx、status.tsx、variant.tsx
import { DatePicker, Flex } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <Flex wrap gap="small">
      <DatePicker size="small" placeholder="small" />
      <DatePicker placeholder="middle" />
      <DatePicker size="large" placeholder="large" />
    </Flex>
    <Flex wrap gap="small">
      <DatePicker status="error" placeholder="error" />
      <DatePicker status="warning" placeholder="warning" />
    </Flex>
    <Flex wrap gap="small">
      <DatePicker variant="filled" placeholder="filled" />
      <DatePicker variant="borderless" placeholder="borderless" />
      <DatePicker variant="underlined" placeholder="underlined" />
    </Flex>
  </Flex>
</template>
```

## 标签与输入属性 (input-attrs)

用 `id` 与原生 `label for` 关联输入框，`aria-describedby` 关联说明。范围选择器使用对象 `id` 分别标记两端。`class/style/data-*` 仍作用于选择器根。

Associate native labels with inputs using `id` and `label for`, and descriptions using `aria-describedby`. Object ids identify each range endpoint. `class/style/data-*` still target the selector root.

### input-attrs.vue

```vue
<script setup lang="ts">
import { DatePicker, Flex, RangePicker } from '@apollo-design/ui';
</script>

<template>
  <Flex gap="small" vertical align="flex-start">
    <label for="demo-date-input">日期 / Date</label>
    <DatePicker id="demo-date-input" name="date" aria-describedby="demo-date-hint" required />
    <span id="demo-date-hint">选择日期，也可以使用键盘输入。 / Pick or type a date.</span>
    <label for="demo-range-start">开始日期 / Start date</label>
    <label for="demo-range-end">结束日期 / End date</label>
    <RangePicker :id="{ start: 'demo-range-start', end: 'demo-range-end' }" />
  </Flex>
</template>
```

## 多选 (multiple)

`multiple` 允许选择多个日期（不支持时间/日期时间）；`maxTagCount="responsive"` 让标签随宽度自适应折叠。

### multiple.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/multiple.tsx
import { DatePicker, Flex } from '@apollo-design/ui';
import dayjs from 'dayjs';
import { ref } from 'vue';

const value = ref([dayjs().add(1, 'day'), dayjs().add(3, 'day')]);
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker v-model:value="value" multiple placeholder="可多选日期" />
    <DatePicker multiple max-tag-count="responsive" placeholder="标签自适应宽度" />
    <div class="demo-hint">已选 {{ Array.isArray(value) ? value.length : 0 }} 天</div>
  </Flex>
</template>
```

## 自定义单元格 (cell-render)

`cellRender` 拿到 `current`、`info.originNode` 与面板类型；示例在每 7 天的格子右下角画一个提示圆点，其余仍返回原始节点。

### cell-render.vue

```vue
<script setup lang="ts">
import { DatePicker } from '@apollo-design/ui';
import dayjs from 'dayjs';

const hasDot = (value: unknown) => dayjs.isDayjs(value) && value.date() % 7 === 0;
</script>

<template>
  <DatePicker placeholder="每 7 天有一个圆点">
    <template #cellRender="{ current, info }">
      <div v-if="info.type === 'date' && hasDot(current)" class="date-picker-custom-cell">
        <component :is="info.originNode" />
        <span class="date-picker-custom-cell-dot" />
      </div>
      <component :is="info.originNode" v-else />
    </template>
  </DatePicker>
</template>

<style scoped>
.date-picker-custom-cell { position: relative; }
.date-picker-custom-cell-dot { position: absolute; inset-inline-end: 2px; bottom: 2px; width: 6px; height: 6px; border-radius: 50%; background: var(--apollo-color-primary); }
</style>
```

## 需要确认 (need-confirm)

`needConfirm` 让面板显示“确定”按钮，只有点击确定后值才提交；适合需要二次确认的录入流程。

### need-confirm.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/need-confirm.tsx
import { DatePicker, Flex } from '@apollo-design/ui';
import dayjs from 'dayjs';
import { ref } from 'vue';

const value = ref(dayjs());
const text = ref(value.value.format('YYYY-MM-DD'));

const onChange = (_date: unknown, dateString: string | string[] | null) => {
  text.value = typeof dateString === 'string' ? dateString : '';
};
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker v-model:value="value" need-confirm @change="onChange" />
    <div class="demo-hint">已提交：{{ text || '（空）' }}</div>
  </Flex>
</template>
```

## 面板底部 (render-extra-footer)

`renderExtraFooter` 接收当前面板粒度，返回值渲染在面板底部，可用于放快捷说明或自定义操作。

### render-extra-footer.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/render-extra-footer.tsx
import { DatePicker } from '@apollo-design/ui';
</script>

<template>
  <DatePicker placeholder="面板底部有额外内容"><template #extraFooter>自定义面板底部内容</template></DatePicker>
</template>
```

## 范围日期时间 (range-picker-time)

范围选择器同样支持 `show-time`；两端分别选择日期与时间，`format` 决定输入框的展示格式。

### range-picker-time.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/range-picker.tsx 的时间范围
import { DatePicker } from '@apollo-design/ui';
</script>

<template>
  <DatePicker.RangePicker
    show-time
    format="YYYY-MM-DD HH:mm"
    :placeholder="['开始时间', '结束时间']"
  />
</template>
```

## 自定义面板 (panel-render)

`panelRender` 拿到原始面板节点与当前面板粒度，返回的节点会替换浮层内容；示例在面板外加了一层边框与提示。

### panel-render.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/panel-render.tsx：包裹原始面板
import { DatePicker } from '@apollo-design/ui';
import { h, type VNodeChild } from 'vue';

const panelRender = (originPanel: VNodeChild) =>
  h(
    'div',
    {
      style: {
        padding: '8px',
        border: '1px solid var(--apollo-color-border)',
        borderRadius: 'var(--apollo-border-radius-lg)',
      },
    },
    [originPanel, h('div', { class: 'demo-hint' }, '自定义面板容器')],
  );
</script>

<template>
  <DatePicker placeholder="自定义面板容器">
    <template #panelRender="{ originPanel }"><component :is="() => panelRender(originPanel)" /></template>
  </DatePicker>
</template>
```

## 弹层位置 (placement)

`placement` 控制浮层相对输入框的落点；空间不足时仍会由触发器自动翻转。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/placement.tsx
import { DatePicker, Flex } from '@apollo-design/ui';
</script>

<template>
  <Flex wrap gap="middle">
    <DatePicker placement="bottomLeft" placeholder="bottomLeft" />
    <DatePicker placement="bottomRight" placeholder="bottomRight" />
    <DatePicker placement="topLeft" placeholder="topLeft" />
    <DatePicker placement="topRight" placeholder="topRight" />
  </Flex>
</template>
```

## 允许空值 (allow-empty)

范围选择器用 `allowEmpty` 指定两端是否允许只选一端；示例要求结束日期必填。

### allow-empty.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/allow-empty.tsx
import { DatePicker } from '@apollo-design/ui';
</script>

<template>
  <DatePicker.RangePicker
    :allow-empty="[true, false]"
    :placeholder="['开始日期（可空）', '结束日期（必填）']"
  />
</template>
```

## 组件 Token (component-token)

在 `DatePicker` 根元素上覆写 `--apollo-date-picker-*` CSS 变量即可定制组件样式，例如 `--apollo-date-picker-active-border-color`、`--apollo-date-picker-hover-border-color`、`--apollo-date-picker-active-shadow`、`--apollo-date-picker-input-font-size`、`--apollo-date-picker-cell-hover-bg` 与 `--apollo-date-picker-presets-width`。打开面板可观察单元格悬浮色。

### component-token.vue

```vue
<script setup lang="ts">
// 组件 Token：在 DatePicker 根元素上覆写真实的 `--apollo-date-picker-*` 变量。
// `ConfigProvider theme.components` 尚未产出组件 CSS 变量，故采用与 alert 等组件
// component-token demo 相同的直接覆写方式。
import { DatePicker } from '@apollo-design/ui';

const pickerTokenStyle = {
  '--apollo-date-picker-active-border-color': '#722ed1',
  '--apollo-date-picker-hover-border-color': '#9254de',
  '--apollo-date-picker-active-shadow': '0 0 0 2px rgb(114 46 209 / 20%)',
  '--apollo-date-picker-input-font-size': '15px',
};

const panelTokenStyle = {
  '--apollo-date-picker-cell-hover-bg': '#f9f0ff',
  '--apollo-date-picker-presets-width': '140px',
};
</script>

<template>
  <div class="demo-picker-token-list">
    <DatePicker
      :style="pickerTokenStyle"
      placeholder="自定义激活边框与阴影"
      aria-label="自定义激活边框与阴影"
    />
    <DatePicker
      :style="panelTokenStyle"
      placeholder="打开面板查看单元格悬浮色"
      aria-label="打开面板查看单元格悬浮色"
    />
    <DatePicker.RangePicker
      :style="pickerTokenStyle"
      :placeholder="['开始日期', '结束日期']"
    />
  </div>
</template>

<style scoped>
.demo-picker-token-list {
  display: flex;
  flex-direction: column;
  gap: 12px;
  align-items: flex-start;
}
</style>
```

## 禁用 (disabled)

`DatePicker` 的 `disabled` 接受布尔值；`DatePicker.RangePicker` 还支持 `[boolean, boolean]` 元组，用来只禁用范围中的某一端。示例同时展示完全禁用、带默认值的禁用状态以及单端禁用。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/disabled.tsx：整框禁用、范围单端禁用与带默认值禁用。
import { DatePicker, Flex } from '@apollo-design/ui';
import dayjs from 'dayjs';
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker disabled placeholder="完全禁用" aria-label="完全禁用的日期选择器" />
    <DatePicker
      disabled
      :default-value="dayjs('2026-10-21')"
      placeholder="禁用且带默认值"
      aria-label="禁用且带默认值的日期选择器"
    />
    <DatePicker.RangePicker
      :disabled="[true, false]"
      :placeholder="['开始日期（禁用）', '结束日期（可选）']"
    />
    <DatePicker.RangePicker disabled :placeholder="['开始日期', '结束日期']" />
    <div class="demo-picker-hint">范围选择器的 `disabled` 支持 `[boolean, boolean]` 单端禁用。</div>
  </Flex>
</template>

<style scoped>
.demo-picker-hint {
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

## 受控面板模式 (mode)

`mode` 用于受控地指定面板粒度（`date` / `month` / `year`）。示例用 `RadioGroup` 修改 `mode`，并通过 `@panel-change` 记录面板切换结果、通过 `@change` 回显最终选择值。

### mode.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/mode.tsx：用受控 `mode` 切换面板粒度，并监听 panelChange。
import type { DatePickerDate, DatePickerPanelMode, SingleValue } from '@apollo-design/ui';
import { DatePicker, Flex, Radio, RadioGroup } from '@apollo-design/ui';
import { ref } from 'vue';

const mode = ref<DatePickerPanelMode>('date');
const panelText = ref('（尚未切换面板）');
const valueText = ref('（未选择）');

const onPanelChange = (value: DatePickerDate, nextMode: DatePickerPanelMode) => {
  panelText.value = `${value.format('YYYY-MM-DD')} → ${nextMode}`;
};

const onChange = (_date: SingleValue, dateString: string | string[] | null) => {
  valueText.value = typeof dateString === 'string' && dateString ? dateString : '（已清空）';
};
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <RadioGroup v-model:value="mode" aria-label="面板粒度">
      <Radio value="date">date</Radio>
      <Radio value="month">month</Radio>
      <Radio value="year">year</Radio>
    </RadioGroup>
    <DatePicker
      :mode="mode"
      placeholder="受控面板模式"
      aria-label="受控面板模式"
      @panel-change="onPanelChange"
      @change="onChange"
    />
    <div class="demo-picker-hint">panelChange：{{ panelText }}</div>
    <div class="demo-picker-hint">当前值：{{ valueText }}</div>
  </Flex>
</template>

<style scoped>
.demo-picker-hint {
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

## 区间内选择 (select-in-range)

`@calendar-change` 会在范围选择的中间过程触发，携带 `info.range` 标识当前选的是起点还是终点；`disabled-date` 的第二个参数 `info.from` 是已选的起点。示例把结束日期限制在起点前后 7 天内，并实时显示选择进度。

### select-in-range.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/select-in-range.tsx：
// calendarChange 记录起点，disabledDate 把可选范围限制在 7 天内。
import type { DisabledDate, RangePickerEmits } from '@apollo-design/ui';
import { DatePicker, Flex } from '@apollo-design/ui';
import dayjs from 'dayjs';
import { ref } from 'vue';

const hint = ref('先选择开始日期，再在 7 天内选择结束日期。');

const disabledDate: DisabledDate = (current, info) => {
  if (current.isBefore(dayjs().startOf('day'))) return true;
  if (!info.from) return false;
  return Math.abs(current.diff(info.from, 'day')) > 7;
};

const onCalendarChange: RangePickerEmits['calendarChange'] = (dates, _dateStrings, info) => {
  if (info.range === 'start' && dates[0]) {
    hint.value = `开始日期：${dates[0].format('YYYY-MM-DD')}，结束日期需在 7 天内。`;
  } else if (info.range === 'end' && dates[1]) {
    hint.value = `已选择：${dates[0]?.format('YYYY-MM-DD') ?? '?'} → ${dates[1].format(
      'YYYY-MM-DD',
    )}`;
  }
};
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker.RangePicker
      :disabled-date="disabledDate"
      :placeholder="['开始日期', '结束日期']"
      @calendar-change="onCalendarChange"
    />
    <div class="demo-picker-hint">{{ hint }}</div>
  </Flex>
</template>

<style scoped>
.demo-picker-hint {
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

## 起止日期联动 (start-end)

两个独立的 `DatePicker` 通过 `disabled-date` 互相限制：开始日期不能晚于已选结束日期，结束日期不能早于已选开始日期。`@change` 回写 `value`，页面下方实时显示当前范围。

### start-end.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/start-end.tsx：两个 DatePicker 互相限制可选范围。
import type { DatePickerDate, DisabledDate, SingleValue } from '@apollo-design/ui';
import { DatePicker, Flex } from '@apollo-design/ui';
import { ref } from 'vue';

const start = ref<DatePickerDate | null>(null);
const end = ref<DatePickerDate | null>(null);

const disabledStart: DisabledDate = (current) =>
  end.value ? current.isAfter(end.value, 'day') : false;

const disabledEnd: DisabledDate = (current) =>
  start.value ? current.isBefore(start.value, 'day') : false;

const onStartChange = (value: SingleValue) => {
  start.value = Array.isArray(value) ? null : value;
};

const onEndChange = (value: SingleValue) => {
  end.value = Array.isArray(value) ? null : value;
};
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <Flex wrap gap="small" align="center">
      <DatePicker
        :value="start"
        :disabled-date="disabledStart"
        placeholder="开始日期"
        aria-label="开始日期"
        @change="onStartChange"
      />
      <span>至</span>
      <DatePicker
        :value="end"
        :disabled-date="disabledEnd"
        placeholder="结束日期"
        aria-label="结束日期"
        @change="onEndChange"
      />
    </Flex>
    <div class="demo-picker-hint">
      当前范围：{{ start?.format('YYYY-MM-DD') ?? '（空）' }} → {{ end?.format('YYYY-MM-DD') ?? '（空）' }}
    </div>
  </Flex>
</template>

<style scoped>
.demo-picker-hint {
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

## 语义化结构样式 (style-class)

`DatePicker` 的 `classNames` / `styles` 提供 `root`、`prefix`、`input`、`suffix` 与 `popup` 语义槽，其中 `popup` 还可细分为 `root` / `header` / `body` / `content` / `item` / `footer` / `container`。示例用类名定制输入区与浮层，用 `styles` 定制输入文字与后缀颜色。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/style-class.tsx：root / input / suffix / popup 语义槽。
import type { DatePickerSemanticClassNames, DatePickerSemanticStyles } from '@apollo-design/ui';
import { DatePicker } from '@apollo-design/ui';

const classNames: DatePickerSemanticClassNames = {
  root: 'demo-picker-root',
  input: 'demo-picker-input',
  suffix: 'demo-picker-suffix',
  popup: {
    root: 'demo-picker-popup',
    header: 'demo-picker-popup-header',
  },
};

const styles: DatePickerSemanticStyles = {
  input: { fontWeight: 500 },
  suffix: { color: '#722ed1' },
};
</script>

<template>
  <div class="demo-picker-style-list">
    <DatePicker
      :class-names="classNames"
      :styles="styles"
      placeholder="自定义语义样式"
      aria-label="自定义语义样式的日期选择器"
    />
    <DatePicker.RangePicker
      :class-names="classNames"
      :styles="styles"
      :placeholder="['开始日期', '结束日期']"
    />
    <div class="demo-picker-hint">
      打开面板可看到 popup.root / popup.header 两个浮层语义槽上的类名。
    </div>
  </div>
</template>

<style scoped>
.demo-picker-style-list {
  display: flex;
  flex-direction: column;
  gap: 12px;
  align-items: flex-start;
}

.demo-picker-hint {
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>

<style>
.demo-picker-root {
  border-radius: 10px;
}

.demo-picker-input {
  letter-spacing: 0.2px;
}

.demo-picker-suffix {
  opacity: 0.9;
}

.demo-picker-popup {
  border: 1px solid #d3adf7;
  border-radius: 10px;
}

.demo-picker-popup-header {
  background: var(--apollo-color-primary-bg);
  color: var(--apollo-color-text);
}
</style>
```

## 自定义后缀图标 (suffix)

通过 `suffix-icon` 传入 `VNodeChild` 可以替换默认日历图标；传入 `null` 则完全不渲染后缀图标。示例用 `h(CalendarOutlined)` 与 `h(SmileOutlined)` 构造图标节点，并保留第三种「无图标」形态。

### suffix.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/suffix.tsx：通过 suffixIcon 替换 / 隐藏面板图标。
import { CalendarOutlined, SmileOutlined } from '@apollo-design/icons';
import { DatePicker, Flex } from '@apollo-design/ui';
import { computed, h } from 'vue';

const calendarIcon = computed(() => h(CalendarOutlined));
const smileIcon = computed(() => h(SmileOutlined));
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker
      :suffix-icon="calendarIcon"
      placeholder="自定义日历图标"
      aria-label="自定义日历图标的日期选择器"
    />
    <DatePicker
      :suffix-icon="smileIcon"
      placeholder="自定义笑脸图标"
      aria-label="自定义笑脸图标的日期选择器"
    />
    <DatePicker
      :suffix-icon="null"
      placeholder="不显示后缀图标"
      aria-label="不显示后缀图标的日期选择器"
    />
  </Flex>
</template>
```

## 可切换粒度 (switchable)

`picker` 支持 `date`、`week`、`month`、`quarter`、`year` 五种粒度。示例用 `RadioGroup` 绑定 `picker`，切换后 `DatePicker` 的输入格式、面板结构与 `@change` 返回的 `dateString` 都会随之变化。

### switchable.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/switchable.tsx：通过 picker 切换日期 / 周 / 月 / 季 / 年粒度。
import type { DatePickerMode, SingleValue } from '@apollo-design/ui';
import { DatePicker, Flex, Radio, RadioGroup } from '@apollo-design/ui';
import { ref } from 'vue';

const picker = ref<DatePickerMode>('date');
const valueText = ref('（未选择）');

const onChange = (_date: SingleValue, dateString: string | string[] | null) => {
  valueText.value = typeof dateString === 'string' && dateString ? dateString : '（已清空）';
};
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <RadioGroup v-model:value="picker" aria-label="选择粒度">
      <Radio value="date">日期</Radio>
      <Radio value="week">周</Radio>
      <Radio value="month">月</Radio>
      <Radio value="quarter">季度</Radio>
      <Radio value="year">年</Radio>
    </RadioGroup>
    <DatePicker
      :picker="picker"
      :placeholder="`当前粒度：${picker}`"
      aria-label="可切换粒度的日期选择器"
      @change="onChange"
    />
    <div class="demo-picker-hint">当前值：{{ valueText }}</div>
  </Flex>
</template>

<style scoped>
.demo-picker-hint {
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

## 时间选择 (time)

`show-time` 打开时间面板，`format` 控制输入框展示格式，`disabled-time` 返回 `{ disabledHours, disabledMinutes, disabledSeconds }` 来禁用具体档位。示例仅允许选择 09:00 到 18:00，并通过 `@change` 显示最终值。

### time.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/time.tsx：showTime + disabledTime 限制可选时段。
import type { DatePickerProps, SingleValue } from '@apollo-design/ui';
import { DatePicker, Flex } from '@apollo-design/ui';
import { ref } from 'vue';

const valueText = ref('（未选择）');

const disabledTime: NonNullable<DatePickerProps['disabledTime']> = () => ({
  disabledHours: () =>
    Array.from({ length: 24 }, (_, hour) => hour).filter((hour) => hour < 9 || hour > 18),
});

const onChange = (_date: SingleValue, dateString: string | string[] | null) => {
  valueText.value = typeof dateString === 'string' && dateString ? dateString : '（已清空）';
};
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <DatePicker
      show-time
      format="YYYY-MM-DD HH:mm"
      :disabled-time="disabledTime"
      placeholder="仅可选 09:00 - 18:00"
      aria-label="仅可选工作时间的日期时间选择器"
      @change="onChange"
    />
    <div class="demo-picker-hint">当前值：{{ valueText }}</div>
  </Flex>
</template>

<style scoped>
.demo-picker-hint {
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

## 日期区间 (date-range)

`DatePicker.RangePicker` 同样支持 `picker` 粒度切换。示例在日期、周、月、年四种粒度间切换，`@change` 的第二个参数始终是长度为 2 的格式化字符串数组，便于直接展示区间结果。

### date-range.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/date-range.tsx：RangePicker 的多种面板粒度与取值回显。
import type { DatePickerMode, NoUndefinedRangeValue } from '@apollo-design/ui';
import { DatePicker, Flex, Radio, RadioGroup } from '@apollo-design/ui';
import { ref } from 'vue';

const picker = ref<DatePickerMode>('date');
const valueText = ref('（未选择）');

const onChange = (_dates: NoUndefinedRangeValue | null, dateStrings: [string, string]) => {
  valueText.value = dateStrings[0] || dateStrings[1] ? dateStrings.join(' → ') : '（已清空）';
};
</script>

<template>
  <Flex vertical align="flex-start" gap="small">
    <RadioGroup v-model:value="picker" aria-label="范围选择粒度">
      <Radio value="date">日期</Radio>
      <Radio value="week">周</Radio>
      <Radio value="month">月</Radio>
      <Radio value="year">年</Radio>
    </RadioGroup>
    <DatePicker.RangePicker
      :picker="picker"
      :placeholder="['开始日期', '结束日期']"
      @change="onChange"
    />
    <div class="demo-picker-hint">当前值：{{ valueText }}</div>
  </Flex>
</template>

<style scoped>
.demo-picker-hint {
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

---

# Descriptions

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/descriptions


成组展示只读字段。原生 `dl` 中的每项由 `dt` 标签与 `dd` 内容组成；支持普通、边框和垂直布局。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/descriptions/demo) 的 13 对演示。模板内容使用 `DescriptionsItem` 插槽，程序化数据使用 `items`。

## API

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| prefixCls | 当前实例 DOM 类名前缀；自定义前缀需自行提供对应静态 CSS | `string` | `apollo-descriptions` |
| id | 原生根 div 的 id | `string` | — |
| bordered | 边框布局 | `boolean` | `false` |
| size | 尺寸；`default` 已废弃，改用 `large`；`middle` 保留 | `'large' \| 'medium' \| 'small' \| 'default' \| 'middle'` | Provider componentSize，未配置为 `large` |
| column | 逻辑列数；映射按命中的最大断点取值，未命中使用默认映射 | `DescriptionsColumn` | `{ xs: 1, sm: 2, md: 3, lg: 3, xl: 3, xxl: 3, xxxl: 4 }` |
| layout | 标签与内容的排列方向 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| colon | 普通布局的标签冒号；边框布局始终隐藏冒号 | `boolean` | `true` |
| title | 文本标题；存在 `#title` 时由插槽替代，含刻意空槽 | `string` | — |
| items | 条目数组；包括 `[]` 时均优先于默认插槽，且不执行被覆盖的插槽 | `DescriptionsItemType[]` | — |
| labelStyle / contentStyle | 已废弃，改用 `styles.label` / `styles.content` | `CSSProperties` | — |
| classNames | 六个语义区域的类名 | `DescriptionsSemanticClassNames \| ((info: { props: DescriptionsProps }) => DescriptionsSemanticClassNames)` | — |
| styles | 六个语义区域的样式 | `DescriptionsSemanticStyles \| ((info: { props: DescriptionsProps }) => DescriptionsSemanticStyles)` | — |

`column` / 数字 `span` 向下取整；非有限数或小于 1 的列数回退到 3，跨度回退到 1。超出本行剩余列位的跨度被压缩，并发开发告警。SSR/首帧没有激活断点时 column 为 3、响应式 span 为 1，挂载后按当前视口更新。

### Slots

| 插槽 | 说明 | 参数 |
| --- | --- | --- |
| default | 由 `DescriptionsItem` / `Descriptions.Item` 构成的条目，支持 Fragment、v-for 和 v-if | 无 |
| title | 完整标题内容；空槽抑制文本后备，0 保留可见 | 无 |
| extra | 标题右侧内容；使用原生按钮或其他 Vue 组件 | 无 |

只把实际 Item 作为描述项，忽略默认槽中其他节点。`items` 与模板 Item 均为正式支持的输入方式。没有业务 emits 或 v-model；原生根事件通过 attrs 接收 DOM 事件一次。空标题/额外内容不生成空壳。

### DescriptionsItemType

| 字段 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| key | 业务身份；动态重排应提供稳定 key | `PropertyKey` | 索引 |
| label / children | 完整标签/内容数据，可含多节点、文本、0、VNode 和 Fragment | `VNodeChild` | — |
| span | 所占逻辑列；`filled` 填满本行剩余列位并结束本行 | `number \| 'filled' \| Partial<Record<Breakpoint, number>>` | `1` |
| prefixCls | 当前条目类名前缀；需提供对应 CSS | `string` | 父组件前缀 |
| className / style | 数据项所属 div 的类名/原生样式 | `string` / `StyleValue` | — |
| classNames / styles | 当前项的 `label` / `content` 区域 | `{ label?, content? }` | — |
| labelStyle / contentStyle | 已废弃的标签/内容样式别名 | `CSSProperties` | — |

每行最后一项填满剩余列位。例：4 项 / 3 列形成 `[1,1,1]` 和 `[3]`；A(1)、B(filled)、C(1) 形成 `[1,2]` 和 `[3]`，B 不另起一行。

### DescriptionsItem

具名导出 `DescriptionsItem` 与静态 `Descriptions.Item` 相同，放在 Descriptions 默认槽中。

| 参数 | 说明 | 类型 |
| --- | --- | --- |
| label | 文本标签；`#label` 存在时优先，含空槽 | `string` |
| span / prefixCls | 与数据项相同 | 见上表 |
| classNames / styles | 当前项的标签/内容类名和样式 | `{ label?, content? }` |
| labelStyle / contentStyle | 保留的已废弃样式别名 | `CSSProperties` |
| className | 已废弃，模板使用原生 `class` | `string` |

`#label` 和默认插槽不带参数，完整接收 Vue 内容。原生 `class`、字符串/对象/数组 `style`、id、data、ARIA、tabindex 和事件落在该项所属 div；父根 attrs 不会进入子项。默认槽中的原生控件保留自身事件与键盘行为。Item 不提供业务 emits、v-model 或额外 expose。

### 样式、配置与生命周期

语义区域为 `root`、`header`、`title`、`extra`、`label`、`content`。根为 div，label/content 在所有布局中均为 dt/dd。类名按 Provider → 组件 → Item 拼接；区域样式为 Provider → 组件旧样式 → 组件 styles → Item 旧样式 → Item styles。根样式为 Provider styles.root → Provider style → 组件 styles.root → Vue 原生 style。

`ConfigProvider.components.descriptions` 接受 `DescriptionsConfig` 的 className/style/classNames/styles；全局 componentSize、direction、prefixCls 和 theme 保持响应。函数式语义参数为 `{ props }`，其中 column 与 size 为当前有效值。嵌套实例独立消费配置，外层区域样式不会改写内层标签。

数据和槽在当前渲染内归一化，不在 render 中写响应式状态。带稳定 key 的内容在换列、span、重排、layout/bordered 切换时保留 Vue 实例、原生节点、草稿与所属焦点；移除项会正常卸载，重新添加是新实例。SSR 不读取浏览器尺寸，水合后开始观察断点。

### Ref

仅公开 `nativeElement: HTMLDivElement | null`，指向实际根元素；卸载时清空。不暴露内部实例。

## Theme（Component Token）

10 个 Token 使用 `--apollo-descriptions-*` CSS 变量；`ConfigProvider.theme.components.Descriptions` 可动态覆盖，移除后恢复当前主题默认值。

| Token | 默认值 | 作用 |
| --- | --- | --- |
| labelBg | colorFillAlter | 边框标签背景 |
| labelColor | colorTextSecondary | 所有布局的标签文字，默认可读 |
| titleColor | colorText | 标题文字 |
| titleMarginBottom | fontSizeSM × lineHeightSM | 标题下间距，跟随当前字体 |
| itemPaddingBottom | padding；medium/middle 为 paddingSM，small 为 paddingXS | 项间距/边框区域纵向 padding |
| itemPaddingEnd | padding | 项尾间距/边框区域横向 padding |
| colonMarginRight / colonMarginLeft | marginXS / marginXXS ÷ 2 | 冒号的行内后/前间距 |
| contentColor | colorText | 内容文字 |
| extraColor | colorText | 额外内容文字 |

长度 Token 接受数字像素值或 CSS 长度字符串，颜色 Token 接受字符串。显式覆盖优先于尺寸默认值，普通与边框布局均消费同一组 Token。布局依赖现代 CSS Grid/Subgrid；保留的语义类名可用于样式迁移，旧 table/tr/th/td 树已按 Vue 内容身份契约替换，见 [迁移说明](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/descriptions-contracts.md)。


## 基本 (basic)

简单的展示：`items` 数据驱动，无断点映射配置时按当前默认断点列数显示，SSR/未激活断点为 3 列（每行末项填满剩余列位）。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { Descriptions } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Product', children: 'Cloud Database' },
  { key: '2', label: 'Billing', children: 'Prepaid' },
  { key: '3', label: 'time', children: '18:00:00' },
  { key: '4', label: 'Amount', children: '$80.00' },
];
</script>

<template>
  <Descriptions :items="items" />
</template>
```

## 带边框 (bordered)

`bordered` 展示边框与 label 背景；原生 dt/dd 标签与内容视觉分格，动态切换布局仍保留同一条目和内容节点。

### bordered.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 bordered demo
import { Descriptions } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Product', children: 'Cloud Database' },
  { key: '2', label: 'Billing', children: 'Prepaid' },
  { key: '3', label: 'time', children: '18:00:00' },
  { key: '4', label: 'Amount', children: '$80.00' },
];
</script>

<template>
  <Descriptions bordered :items="items" />
</template>
```

## 垂直 (vertical)

`layout="vertical"`：视觉上标签在上、内容在下；每项仍使用稳定的 dt/dd，DOM 读取顺序为标签后跟内容。

### vertical.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 vertical demo
import { Descriptions } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Product', children: 'Cloud Database' },
  { key: '2', label: 'Billing', children: 'Prepaid' },
  { key: '3', label: 'time', children: '18:00:00' },
];
</script>

<template>
  <Descriptions layout="vertical" :items="items" />
</template>
```

## 自定义尺寸 (size)

`size="small"` / `"medium"` / `"large"`（默认）。⚠️ `'default'` 已废弃并提示改用 `'large'`。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size demo（⚠️ 'default' 已废弃，提示改 'large'）
import { Descriptions } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Product', children: 'Cloud Database' },
  { key: '2', label: 'Billing', children: 'Prepaid' },
  { key: '3', label: 'time', children: '18:00:00' },
];
</script>

<template>
  <Descriptions size="small" title="Small" :items="items" style="margin-bottom: 24px" />
  <Descriptions size="medium" title="Medium" :items="items" style="margin-bottom: 24px" />
  <Descriptions title="Large（默认）" :items="items" />
</template>
```

## 标题与额外内容 (extra)

`title` / `#extra` 插槽渲染在 `-header` 块（仅二者之一存在时才渲染）；`:colon="false"` 去掉冒号（label 加 `-no-colon` 类）。

### extra.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 Extra / colon demo
import { Button, Descriptions } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Product', children: 'Cloud Database' },
  { key: '2', label: 'Billing', children: 'Prepaid' },
  { key: '3', label: 'time', children: '18:00:00' },
];
</script>

<template>
  <Descriptions title="Order Detail" :items="items" :colon="false">
    <template #extra><Button size="small">操作按钮</Button></template>
  </Descriptions>
</template>
```

## 自定义条目 (custom-item)

`DescriptionsItem` / `Descriptions.Item` 均为正式支持的模板用法。`#label` 与默认槽保留完整内容，条目级 `styles` 与 `span` 控制样式和逻辑跨度。`filled` 填满当前行剩余列位并收尾；切换布局会保留输入框的原生节点和草稿。

### custom-item.vue

```vue
<script setup lang="ts">
// 原生 Item 插槽与样式；切换布局仍保留内容实例。
import { Button, Descriptions, DescriptionsItem, Input } from '@apollo-design/ui';
import { ref } from 'vue';

const vertical = ref(false);
</script>

<template>
  <Descriptions title="Styles & span" :layout="vertical ? 'vertical' : 'horizontal'">
    <template #extra><Button size="small" @click="vertical = !vertical">切换布局</Button></template>
    <DescriptionsItem label="Styles" :styles="{ content: { fontWeight: 600 } }">
      <template #label><strong>原生</strong>标签</template>
      <Input aria-label="保留的草稿" default-value="切换布局后仍保留草稿" style="max-width: 100%" />
    </DescriptionsItem>
    <DescriptionsItem label="Span" :span="2">占两列</DescriptionsItem>
    <DescriptionsItem label="Filled" span="filled">填满本行剩余列位</DescriptionsItem>
  </Descriptions>
</template>
```

## 列数 (column)

`column` 控制每行列数，通过下拉框切换即可看到条目重新排布。

### column.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 column demo：下拉框切换列数
import { Descriptions, Select } from '@apollo-design/ui';
import { ref } from 'vue';

const column = ref(3);

const columnOptions = [1, 2, 3, 4].map((value) => ({ value, label: `${value} 列` }));

const items = [
  { key: '1', label: '产品', children: '云数据库' },
  { key: '2', label: '计费方式', children: '预付费' },
  { key: '3', label: '可用区', children: '华东 1' },
  { key: '4', label: '到期时间', children: '2026-12-31' },
  { key: '5', label: '实例规格', children: '4 核 8 GB' },
  { key: '6', label: '状态', children: '运行中' },
];

const onColumnChange = (value: unknown) => {
  column.value = Number(value);
};
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 16px">
    <span>column：</span>
    <Select
        aria-label="列数"
      :value="column"
      :options="columnOptions"
      style="width: 100px"
      @change="onColumnChange"
    />
  </div>
  <Descriptions bordered :column="column" :items="items" />
</template>
```

## 响应式列数 (responsive)

`column` 支持断点映射（`xs` / `sm` / `md`），页面顶部用 `useBreakpoint` 显示当前命中断点。

### responsive.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 responsive demo：column 断点映射
import { Descriptions, useBreakpoint } from '@apollo-design/ui';
import { computed } from 'vue';

const screens = useBreakpoint();

const activeBreakpoint = computed(() => {
  const current = screens.value ?? {};
  return (
    (['xxxl', 'xxl', 'xl', 'lg', 'md', 'sm', 'xs'] as const).find(
      (breakpoint) => current[breakpoint],
    ) ?? '未命中'
  );
});

const items = [
  { key: '1', label: '产品', children: '云数据库' },
  { key: '2', label: '计费方式', children: '预付费' },
  { key: '3', label: '可用区', children: '华东 1' },
  { key: '4', label: '到期时间', children: '2026-12-31' },
  { key: '5', label: '实例规格', children: '4 核 8 GB' },
  { key: '6', label: '状态', children: '运行中' },
];
</script>

<template>
  <p>当前命中断点：<strong>{{ activeBreakpoint }}</strong>（调整浏览器宽度观察列数变化）</p>
  <Descriptions bordered :column="{ xs: 1, sm: 2, md: 3 }" :items="items" />
</template>
```

## 自定义标签 (custom-label)

`items[].label` 接受 VNode，这里用 `Tooltip` 和有名称的 Apollo 问号按钮补充标签说明。鼠标悬浮和键盘 Tab 聚焦均可打开说明；图标只作装饰。

### custom-label.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 custom-label demo：items[].label 接受 VNode
import { QuestionCircleOutlined } from '@apollo-design/icons';
import { Button, Descriptions, Tooltip } from '@apollo-design/ui';
import { h } from 'vue';

const label = (text: string, tip: string) =>
  h('span', { style: { display: 'inline-flex', alignItems: 'center', gap: '4px' } }, [
    text,
    h(Tooltip, { title: tip, trigger: ['hover', 'focus'] }, () =>
      h(
        Button,
        {
          type: 'text',
          size: 'small',
          'aria-label': `${text}说明`,
          style: {
            display: 'inline-flex',
            padding: '2px',
            border: 0,
            background: 'transparent',
            color: 'var(--apollo-color-primary)',
            cursor: 'help',
          },
        },
        { icon: () => h(QuestionCircleOutlined, { 'aria-hidden': 'true' }) },
      ),
    ),
  ]);

const items = [
  { key: '1', label: label('产品', '产品的展示名称'), children: '云数据库' },
  { key: '2', label: label('计费方式', '按量付费或包年包月'), children: '预付费' },
  { key: '3', label: label('到期时间', '到期后资源自动释放'), children: '2026-12-31' },
  { key: '4', label: label('状态', '实例当前的运行状态'), children: '运行中' },
];
</script>

<template>
  <Descriptions bordered :items="items" />
  <p>悬浮或使用 Tab 聚焦问号按钮，查看标签说明。</p>
</template>
```

## 单元格间距 (padding)

当前组件没有 `padding` prop，用语义化 `styles.label` / `styles.content` 覆盖单元格内边距，下拉框可切换三档。

### padding.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 padding demo：用语义化 styles 覆盖单元格内边距
import { Descriptions, Select } from '@apollo-design/ui';
import { computed, ref } from 'vue';

type PaddingMode = 'default' | 'compact' | 'loose';

const padding = ref<PaddingMode>('default');

const paddingOptions = [
  { value: 'default', label: '默认' },
  { value: 'compact', label: '紧凑' },
  { value: 'loose', label: '宽松' },
];

const paddingMap: Record<PaddingMode, string | undefined> = {
  default: undefined,
  compact: '4px 8px',
  loose: '20px 28px',
};

const itemStyles = computed(() => {
  const value = paddingMap[padding.value];
  return value ? { label: { padding: value }, content: { padding: value } } : undefined;
});

const items = [
  { key: '1', label: '产品', children: '云数据库' },
  { key: '2', label: '计费方式', children: '预付费' },
  { key: '3', label: '到期时间', children: '2026-12-31' },
  { key: '4', label: '状态', children: '运行中' },
];

const onPaddingChange = (value: unknown) => {
  if (value === 'default' || value === 'compact' || value === 'loose') padding.value = value;
};
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 16px">
    <span>单元格 padding：</span>
    <Select
        aria-label="单元格内边距"
      :value="padding"
      :options="paddingOptions"
      style="width: 120px"
      @change="onPaddingChange"
    />
  </div>
  <Descriptions bordered :items="items" :styles="itemStyles" />
</template>
```

## 标题与操作区 (extra-button)

`#title` / `#extra` 插槽承载富标题与按钮，点击按钮会累计次数并即时显示。

### extra-button.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 extra demo：title / extra 插槽承载富内容
import { Button, Descriptions, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const count = ref(0);

const items = [
  { key: '1', label: '产品', children: '云数据库' },
  { key: '2', label: '计费方式', children: '预付费' },
  { key: '3', label: '到期时间', children: '2026-12-31' },
  { key: '4', label: '状态', children: '运行中' },
];

const onEdit = () => {
  count.value += 1;
};
</script>

<template>
  <Descriptions :items="items">
    <template #title>
      <Space size="small">
        <span>订单详情</span>
        <span style="color: var(--apollo-color-text-secondary)">#20261021</span>
      </Space>
    </template>
    <template #extra>
      <Button type="primary" size="small" @click="onEdit">编辑（{{ count }}）</Button>
    </template>
  </Descriptions>
  <p>点击「编辑」累计次数：{{ count }}</p>
</template>
```

## 组件 Token (component-token)

本例展示全部 10 个 Token。通过根元素的 `--apollo-descriptions-*` 组件 Token 变量自定义 label / 内容文字颜色、label 背景与条目间距。

上方为普通形态，下方为带边框形态，共用同一组有效 Token；自定义深色文字配对白色背景。也可使用 ConfigProvider.theme.components.Descriptions 动态配置。

### component-token.vue

```vue
<script setup lang="ts">
// 组件 Token：在根元素覆写 `--apollo-descriptions-*` 变量。
import type { DescriptionsItemType } from '@apollo-design/ui';
import { Descriptions } from '@apollo-design/ui';

const items: DescriptionsItemType[] = [
  { key: '1', label: 'Product', children: 'Cloud Database' },
  { key: '2', label: 'Billing', children: 'Prepaid' },
  { key: '3', label: 'Time', children: '18:00:00' },
  { key: '4', label: 'Amount', children: '$80.00' },
];

const tokenStyle = {
  backgroundColor: '#fff',
  padding: '12px',
  '--apollo-descriptions-label-bg': '#f0f5ff',
  '--apollo-descriptions-label-color': '#1d39c4',
  '--apollo-descriptions-title-color': '#10239e',
  '--apollo-descriptions-title-margin-bottom': '24px',
  '--apollo-descriptions-content-color': '#10239e',
  '--apollo-descriptions-extra-color': '#1d39c4',
  '--apollo-descriptions-item-padding-bottom': '12px',
  '--apollo-descriptions-item-padding-end': '24px',
  '--apollo-descriptions-colon-margin-left': '6px',
  '--apollo-descriptions-colon-margin-right': '10px',
};
</script>

<template>
  <div class="descriptions-component-token-demo">
    <Descriptions title="Plain palette" :column="2" :items="items" :style="tokenStyle"><template #extra>Custom palette</template></Descriptions>
    <Descriptions title="Bordered palette" bordered :column="2" :items="items" :style="tokenStyle"><template #extra>Custom palette</template></Descriptions>
  </div>
</template>

<style scoped>
.descriptions-component-token-demo {
  display: flex;
  flex-direction: column;
  gap: 24px;
}
</style>
```

## 垂直带边框 (vertical-border)

`layout="vertical"` 与 `bordered` 组合展示 label 在上、内容在下的带边框布局，并通过 `classNames` / `styles` 自定义 label 与内容样式。

点击右上角按钮可以切换边框，观察带边框与无边框两种形态。

### vertical-border.vue

```vue
<script setup lang="ts">
// 垂直带边框：`layout="vertical"` + `bordered`，并叠加语义化样式。
import type { DescriptionsItemType } from '@apollo-design/ui';
import { Button, Descriptions } from '@apollo-design/ui';
import { ref } from 'vue';

const bordered = ref(true);

const items: DescriptionsItemType[] = [
  { key: '1', label: 'Product', children: 'Cloud Database' },
  { key: '2', label: 'Billing', children: 'Prepaid' },
  { key: '3', label: 'Time', children: '18:00:00' },
  { key: '4', label: 'Amount', children: '$80.00' },
  { key: '5', label: 'Discount', children: '20%' },
  { key: '6', label: 'Status', children: 'Running' },
];

const classNames = { label: 'demo-descriptions-vertical-label' };
const styles = {
  label: { color: 'var(--apollo-color-text)', fontWeight: 600 },
  content: { color: 'var(--apollo-color-text)' },
};
</script>

<template>
  <Descriptions
    :bordered="bordered"
    layout="vertical"
    :column="3"
    :items="items"
    :class-names="classNames"
    :styles="styles"
  >
    <template #extra>
      <Button size="small" @click="bordered = !bordered">
        {{ bordered ? '隐藏边框' : '显示边框' }}
      </Button>
    </template>
  </Descriptions>
</template>

<style>
.demo-descriptions-vertical-label {
  letter-spacing: 0.02em;
}
</style>
```

---

# Divider

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/divider


区隔章节正文或行内操作。支持水平/垂直方向、完整 Vue 标题内容、线型、间距及当前主题。

## 代码演示

九对 Demo 见 [demo](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/divider/demo)：horizontal、with-text、size、plain、vertical、customize-style、component-token、variant、style-class。条件标题、三个真实 Token 和函数式样式提供可操作控件。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | 完整组件类名前缀 | string | 当前 ConfigProvider，兜底 apollo-divider |
| orientation | 方向；旧标题位置值仍接受并告警 | Orientation \| TitlePlacement | 生效方向 horizontal |
| vertical | 是否垂直；明确 false 会压过 type | boolean | 未传为 undefined |
| titlePlacement | 逻辑 start/end、center 或物理 left/right | 'start' \| 'end' \| 'center' \| 'left' \| 'right' | center |
| plain | 标题使用正文样式 | boolean | false |
| variant | 线型；dotted 优先于 dashed 布尔项 | 'solid' \| 'dashed' \| 'dotted' | solid |
| dashed | 虚线开关；保留与 variant 组合 | boolean | false |
| size | 水平间距；medium/middle 等价，垂直模式忽略 | 'small' \| 'medium' \| 'middle' \| 'large' | 继承 componentSize |
| classNames | 三语义区域的类名或函数 | DividerSemanticValue<DividerSemanticClassNames> | — |
| styles | 三语义区域的样式或函数 | DividerSemanticValue<DividerSemanticStyles> | — |
| ~~type~~ | 旧方向配置，改用 orientation | Orientation | — |
| ~~orientationMargin~~ | start/end 标题距近边的长度，建议新代码用 styles.content.margin | string \| number | — |

`Orientation` 为 horizontal / vertical；`TitlePlacement` 为五种标题位置。方向优先级为 orientation（有效方向）→ 显式 vertical → type → horizontal。orientation 的旧位置值不承担方向，并输出迁移告警。

标题的 left/right 按当前方向折算为 start/end。Provider direction 与根原生 dir 更新生效；原生 ltr/rtl dir 优先。size=small 使用 marginXS，medium/middle 使用 margin；large 保留基础间距（普通线 marginLG，标题 margin）。

orientationMargin 的数值和十进制数字字符串（含符号/小数）按 px 处理；CSS 单位串原样使用，0 有效，center 不使用该字段。注意它是像素/长度配置；同名组件 Token 则是 0～1 的比例。

### 原生 attrs、事件和 ref

单一根为 div。无标题/垂直根使用 separator；有水平标题时根使用 group，空 start rail 承担 separator，另一段 rail 是隐藏的装饰，完整标题控件不被交互角色包裹。class、style、id、ARIA 和原生监听到达当前根；class 可为字符串、数组或对象，style 可为字符串、对象或数组，原生 style 优先。垂直根声明 aria-orientation=vertical；水平使用 separator 默认轴。role 按上述实际内容结构派生。

无业务 emits、v-model 或内部键盘操作。槽中的输入、链接、按钮保持原生事件和焦点行为。`nativeElement` 暴露实际 div，挂载前/卸载后为空，不暴露内部实例。

### 插槽与语义区域

默认槽为 `() => VNodeChild`，支持文本、0、数组/Fragment 和元素。条件插入/移除槽立即更新标题；存在但有意为空的槽仍是标题槽。垂直模式不渲染标题并告警。

classNames / styles 的区域为 root、rail、content。无标题时 rail 到根；有水平标题时到两侧 rail。类名按来源拼接；样式优先级为 Provider styles → Provider style(root) → 本地 styles → 原生根 style。语义函数收到 `{ props }`，其中 orientation、titlePlacement、size 是当前有效值。

ConfigProvider 支持 `divider` / `components.divider` 的 className、style、classNames、styles 默认值；组件 size 优先于当前 componentSize。配置替换与清除不需要重新挂载。

### 组件 Token 与主题

| Token | 默认值 | 说明 |
|---|---|---|
| textPaddingInline | 1em | 标题水平内间距；数值按 px |
| orientationMargin | 0.05 | 标题靠边 rail 占比，有限数 0～1 |
| verticalMarginInline | 当前 marginXS | 垂直分割线横向外间距；数值按 px |

```vue
<ConfigProvider :theme="{ components: { Divider: { textPaddingInline: 12, orientationMargin: 0.2, verticalMarginInline: 16 } } }">
  <Divider title-placement="start">Section</Divider>
  <Divider orientation="vertical" />
</ConfigProvider>
```

三个值均可动态更新和复位；空/非有限值使用各自默认值，padding 不接受负数值，margin 支持负长度。读取最近有效 ThemeProvider/ConfigProvider；ThemeProvider 不全局注入 CSS 也能生效，显式空 ThemeProvider 复位默认值。空 ConfigProvider theme 继承外层来源，使用 inherit: false 复位。无主题来源时保留用户 CSS 变量继承。支持默认、暗色、紧凑与嵌套作用域。

### 导出和样式

根入口导出 Divider、DividerProps、DividerRef、DividerConfig、DividerSize、DividerVariant、Orientation、TitlePlacement、语义类型及 DividerSlot。`@apollo-design/ui/divider` 另提供 default、DividerComponentToken、genDividerStyle、prepareDividerComponentToken。注册名为 ADivider。

```ts
import '@apollo-design/theme/tokens.css';
import '@apollo-design/ui/divider/style.css';
// 汇总入口：@apollo-design/ui/style.css
```

静态 CSS 默认覆盖 apollo。自定义命名空间须预生成/加载 CSS，例如 `genDividerStyle('my-app')` 对应 ConfigProvider prefixCls=my-app 或 Divider prefixCls=my-app-divider。函数入参是命名空间，组件 prop 是完整前缀；不会运行时生成任意选择器。


## 水平分割线 (horizontal)

水平分割线区隔真实正文；dashed 切换为虚线。默认样式读取当前作用域的主题变量。

### horizontal.vue

```vue
<script setup lang="ts">
import { Divider } from '@apollo-design/ui';
</script>

<template>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider />
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider dashed />
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
</template>
```

## 带文字的分割线 (with-text)

`titlePlacement` 支持 start / center / end，以及物理方向 left / right。默认槽支持完整 Vue 内容；开关演示条件槽，plain 更新保持仍存在的标题输入。垂直模式不渲染标题。新代码可用 `styles.content.margin` 调整标题外边距。

### with-text.vue

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Checkbox, Divider, Input } from '@apollo-design/ui';

const showTitle = ref(true);
const plain = ref(false);
const draft = ref('Draft title');
</script>

<template>
  <div class="divider-title-controls">
    <Checkbox v-model:checked="showTitle">Show title</Checkbox>
    <Checkbox v-model:checked="plain">Plain title</Checkbox>
  </div>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider :plain="plain">
    <template v-if="showTitle" #default>
      <strong>Text</strong><Input v-model:value="draft" class="divider-title-draft" aria-label="Divider title draft" size="small" />
    </template>
  </Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider title-placement="start">Left Text</Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider title-placement="end">Right Text</Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider title-placement="start" :styles="{ content: { margin: 0 } }">
    Left Text margin with 0
  </Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider title-placement="end" :styles="{ content: { margin: '0 50px' } }">
    Right Text margin with 50px
  </Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
</template>

<style scoped>
.divider-title-controls { display: flex; flex-wrap: wrap; gap: 16px; }
.divider-title-draft { width: min(10rem, 32vw); margin-inline-start: 8px; }
</style>
```

## 设置分割线的间距大小 (size)

`size` 调整水平分割线的纵向间距，vertical 不使用它。small 使用 marginXS，medium / middle 使用 margin；large 保留基础间距（普通线 marginLG，带标题 margin）。也可继承当前 ConfigProvider.componentSize。

### size.vue

```vue
<script setup lang="ts">
import { Divider } from '@apollo-design/ui';
</script>

<template>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider size="small" />
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider size="medium" />
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider size="large" />
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
</template>
```

## 分割文字使用正文样式 (plain)

`plain` 让标题使用正文颜色、字号和字重。文本、具名根样式和当前主题仍正常生效。

### plain.vue

```vue
<script setup lang="ts">
import { Divider } from '@apollo-design/ui';
</script>

<template>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider plain>Text</Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider title-placement="start" plain>Left Text</Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider title-placement="end" plain>Right Text</Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
</template>
```

## 垂直分割线 (vertical)

`orientation="vertical"` 与 `vertical` 均支持；同时配置时 orientation 优先。根声明垂直 separator 语义；标题槽在该模式下忽略并告警。两侧链接保留原生键盘与焦点行为。

### vertical.vue

```vue
<script setup lang="ts">
import { Divider } from '@apollo-design/ui';
</script>

<template>
  Text
  <Divider orientation="vertical" />
  <a href="#" aria-label="Apollo Design component examples">Link</a>
  <Divider vertical />
  <a href="#" aria-label="Apollo Design component examples">Link</a>
</template>

<style scoped>
a { color: inherit; text-decoration: underline; }
</style>
```

## 样式自定义 (customize-style)

根 `class` / `style` 使用 Vue 原生 attrs；字符串、对象或数组 style 按 Vue 规则合并，优先于 Provider 与 `styles.root`。CSS 长度写完整单位，例如 borderWidth: '2px'。

### customize-style.vue

```vue
<script setup lang="ts">
import { Divider } from '@apollo-design/ui';
</script>

<template>
  <Divider :style="{ borderWidth: '2px', borderColor: '#7cb305' }" />
  <Divider :style="{ borderColor: '#7cb305' }" dashed />
  <Divider :style="{ borderColor: '#7cb305' }" dashed>Text</Divider>
  <Divider vertical :style="{ height: '60px', borderColor: '#7cb305' }" />
  <Divider vertical :style="{ height: '60px', borderColor: '#7cb305' }" dashed />

  <div
    :style="{
      display: 'flex',
      flexDirection: 'column',
      height: '50px',
      boxShadow: '0 0 1px red',
    }"
  >
    <Divider :style="{ background: 'rgba(0,255,0,0.05)' }" title-placement="start">Text</Divider>
  </div>
</template>
```

## 组件 Token (component-token)

三个组件 Token 都通过 `ConfigProvider.theme.components.Divider` 生效。使用有名称的原生滑块调整文本 padding、标题靠边比例和垂直分割线的 margin；关闭主题或重置后恢复默认值。数字长度按 px 处理，比例保持无单位。

### component-token.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue';
import { Button, Checkbox, ConfigProvider, Divider, Slider } from '@apollo-design/ui';

const enabled = ref(true);
const padding = ref(12);
const ratio = ref(0.2);
const margin = ref(16);
const theme = computed(() =>
  enabled.value
    ? {
        components: {
          Divider: {
            textPaddingInline: padding.value,
            orientationMargin: ratio.value,
            verticalMarginInline: margin.value,
          },
        },
      }
    : {},
);
function reset() {
  padding.value = 16;
  ratio.value = 0.05;
  margin.value = 8;
  enabled.value = false;
}
</script>

<template>
  <div class="divider-token-controls">
    <Checkbox v-model:checked="enabled">Enable component theme</Checkbox>
    <div>Text padding: {{ padding }}px<Slider v-model:value="padding" aria-label="Divider text padding" :min="0" :max="40" :step="2" /></div>
    <div>Edge ratio: {{ ratio }}<Slider v-model:value="ratio" aria-label="Divider edge ratio" :min="0" :max="1" :step="0.05" /></div>
    <div>Vertical margin: {{ margin }}px<Slider v-model:value="margin" aria-label="Divider vertical margin" :min="0" :max="32" :step="2" /></div>
    <Button style="width: fit-content" @click="reset">Reset Divider theme</Button>
  </div>
  <ConfigProvider :theme="theme">
    <Divider title-placement="start">Section heading</Divider>
    <div class="divider-token-inline"><span>First column</span><Divider orientation="vertical" /><span>Second column</span></div>
  </ConfigProvider>
</template>

<style scoped>
.divider-token-controls { display: grid; gap: 12px; }
.divider-token-inline { margin-block: 16px; }
</style>
```

## 变体 (variant)

线型为 solid / dashed / dotted。dashed 布尔项仍可使用；与 dotted 同时设置时，dotted 控制实际根线和标题两侧的 rail。

### variant.vue

```vue
<script setup lang="ts">
import { Divider } from '@apollo-design/ui';
</script>

<template>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider :style="{ borderColor: '#7cb305' }">Solid</Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider variant="dotted" :style="{ borderColor: '#7cb305' }">Dotted</Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
  <Divider variant="dashed" :style="{ borderColor: '#7cb305' }" dashed>Dashed</Divider>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista
    probare, quae sunt a te dicta? Refert tamen, quo modo.
  </p>
</template>
```

## 自定义语义结构的样式和类 (style-class)

`classNames` / `styles` 支持 root / rail / content 三个语义区域，也支持 `(info: { props }) => 对象`。函数接收当前有效方向、位置和尺寸；原生选择框更新 size，立即改变样式函数结果。类名拼接，样式按来源顺序覆盖，原生根 style 优先。

### style-class.vue

```vue
<script setup lang="ts">
import { ref } from 'vue';
import type { DividerProps } from '@apollo-design/ui';
import { Divider, Select } from '@apollo-design/ui';

const size = ref<DividerProps['size']>('small');

const classNamesObject: DividerProps['classNames'] = {
  root: 'demo-divider-root',
  content: 'demo-divider-content',
  rail: 'demo-divider-rail',
};

const classNamesFn: DividerProps['classNames'] = (info) =>
  info.props.titlePlacement === 'start'
    ? { root: 'demo-divider-root--start' }
    : { root: 'demo-divider-root--default' };

const stylesObject: DividerProps['styles'] = {
  root: { borderWidth: '2px', borderStyle: 'dashed' },
  content: { fontStyle: 'italic' },
  rail: { opacity: 0.85 },
};

const stylesFn: DividerProps['styles'] = (info) =>
  info.props.size === 'small'
    ? { root: { borderColor: 'var(--apollo-color-primary)', paddingBlock: '4px' } }
    : {
        root: {
          backgroundColor: 'var(--apollo-color-fill-alter)',
          borderColor: 'var(--apollo-color-border)',
        },
      };
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px">Semantic size <Select v-model:value="size" aria-label="Divider semantic size" style="width: 140px" :options="[{ value: 'small', label: 'Small' }, { value: 'medium', label: 'Medium' }, { value: 'middle', label: 'Middle' }, { value: 'large', label: 'Large' }]" /></div>
    <Divider :class-names="classNamesObject">classNames Object</Divider>
    <Divider title-placement="start" :class-names="classNamesFn">classNames Function</Divider>
    <Divider :styles="stylesObject">styles Object</Divider>
    <Divider :size="size" :styles="stylesFn">styles Function</Divider>
  </div>
</template>

<style scoped>
.demo-divider-root { border-color: var(--apollo-color-primary); }
:deep(.demo-divider-content) { letter-spacing: 0.03em; }
</style>
```

---

# Drawer

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/drawer


屏幕边缘滑出的浮层面板。

## 何时使用

- 需要从屏幕边缘滑出、承载较多内容或表单的场景。
- 需要在**当前节点内**渲染（`:get-container="false"`）而不是挂到 body。
- 需要可拖拽改尺寸（`resizable`）或多层嵌套（子抽屉推挤父级）。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/drawer/demo)（18 个，覆盖 antd 的主要用户场景）。

## API

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| open | 是否显示 | `boolean` | `false` |
| placement | 方位 | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` |
| size | 尺寸预设或数值/字符串 | `'default' \| 'large' \| number \| string` | `'default'`(378) |
| defaultSize | 默认尺寸（**垂直方位的默认值来源**） | `number` | `378` |
| maxSize | 拖拽时允许的最大尺寸 | `number` | — |
| title | 标题（文本；富标题走 `#title` slot，slot 优先） | `string` | — |
| footer | 页脚（⚠️ 已改为 `#footer` slot，空 slot 等价隐藏） | `slot` | — |
| extra | 标题栏右侧（⚠️ 已改为 `#extra` slot） | `slot` | — |
| closable | 关闭按钮。`false` ⇒ 不渲染；对象可给 `placement: 'start' \| 'end'` | `boolean \| null \| {...}` | `true` |
| closeIcon | 自定义关闭图标（⚠️ 已改为 `#closeIcon` slot） | `slot` | — |
| loading | 内容区骨架态 | `boolean` | `false` |
| mask | 遮罩。`false` ⇒ 无遮罩（根类加 `no-mask`） | `boolean \| { enabled?, blur?, closable? }` | `true` |
| maskClosable | 点遮罩关闭（⚠️ deprecated ⇒ `mask.closable`） | `boolean` | `true` |
| push | 推挤：`true` / `{ distance }`（**只有子抽屉会真的推**） | `boolean \| PushState` | `{ distance: 180 }` |
| resizable | 可拖拽改尺寸；通知使用下表的 Vue 事件 | `boolean` | `false` |
| getContainer | 容器；false 为内联渲染，其他值由 Portal 解析 | `GetContainer` | 默认 body 内的容器 |
| destroyOnHidden | 关闭后卸载 | `boolean` | `false` |
| forceRender | 未打开时也挂载正文，不参与活动 Escape 栈 | `boolean` | `false` |
| focusable | 焦点归还和陷阱；显式 trap 优先，默认仅非内联且有遮罩时锁定 | `{ focusTriggerAfterClose?, trap? }` | — |
| focusTriggerAfterClose | 覆盖 focusable 中的关闭后焦点归还开关 | `boolean` | `true` |
| keyboard | ESC 可关 | `boolean` | `true` |
| autoFocus | 打开时自动聚焦面板 | `boolean` | `true` |
| rootStyle | 根样式，原生 style 的优先级更高 | `CSSProperties` | — |
| zIndex | 显式根层级；未传时使用当前主题和嵌套层级 | `number` | — |
| classNames / styles | 12 个语义槽 | — | — |

`open` 是受控开关。关闭按钮、遮罩和 Escape 仅发出关闭请求，父组件在接受后更新 `open`。`destroyOnHidden` 等待真实离场完成后卸载；条件卸载也清理焦点锁、拖拽和推挤登记。

显式 `size`（及当前方位的 width/height 别名）保持受控，拖拽只发出尺寸请求；未传时使用默认尺寸并在本地调整。撤除受控尺寸时保留最后实际接受的值，不应用被拒绝的请求。

### Events

| 事件 | 说明 | 载荷 |
|---|---|---|
| close | 遮罩点击、关闭按钮或活动层的 Escape 请求 | 原始 `Event`（MouseEvent / KeyboardEvent） |
| afterOpenChange | 打开或关闭动效完成 | `open: boolean` |
| resizeStart | 开始拖拽 | `size: number`，像素 |
| resize | 拖拽后的当前尺寸 | `size: number`，像素 |
| resizeEnd | 正常结束拖拽后的实测尺寸 | `size: number`，像素 |

事件支持 Vue 的 `.once` 和监听数组。关闭、禁用拖拽、切换方位或卸载会释放拖拽监听，不伪造正常结束通知。

**deprecated（9 条，dev 告警）**：`headerStyle` / `bodyStyle` / `footerStyle` →
`styles.*`；`contentWrapperStyle` → `styles.wrapper`；`maskStyle` → `styles.mask`；
`drawerStyle` → `styles.section`；`destroyOnClose` → `destroyOnHidden`；
`width` / `height` → `size`。

### 语义化槽位（12 个）

```
root / mask / wrapper / section / header / title / extra / body / footer / close / dragger
（+ deprecated 的 content ⇒ section）
```

### Slots（C8-R2）

| Slot | 说明 | 参数 |
|---|---|---|
| title | 富标题（文本 `title` prop 等价，slot 优先） | — |
| footer | 页脚（空 slot 等价隐藏） | — |
| extra | 标题栏右侧额外内容 | — |
| closeIcon | 自定义关闭图标 | — |

内容插槽通过 `DrawerSlots` 导出类型；存在即优先（含空内容）。标题在每次 Drawer 渲染中求值一次，面板内容与自动 `aria-labelledby` 共用同一快照；显式 `aria-labelledby` 指向外部标题时保留调用方值。头尾内容显隐不重挂载正文，保留输入状态和 DOM 身份。

`getContainer` 使用 Portal 的完整 `GetContainer` 类型，包括 `false`、选择器、元素与容器函数；Vue 模板可直接传 `:get-container="false"`。Drawer 的原生 `class` / `style`（含数组、对象及字符串）、data 属性与普通 DOM 事件属于外层根；id、role 和 ARIA 属于实际 dialog。面板外观使用 `classNames.section` / `styles.section`。PurePanel 的原生 attrs 全部属于自身根。

### Ref 与开发版迁移

`DrawerRef` 暴露 `nativeElement: HTMLElement | null` 和 `focus(options?: FocusOptions)`，指向当前外层根；销毁前后元素可为空。使用实际模板引用：

```vue
<script setup lang="ts">
import { Drawer, type DrawerRef } from '@apollo-design/ui';
import { ref, useTemplateRef } from 'vue';
const drawer = useTemplateRef<DrawerRef>('drawer');
const open = ref(false);
const completed = (open: boolean) => console.log(open);
</script>
<template>
  <button @click="open = true">Open drawer</button>
  <Drawer ref="drawer" :open="open" resizable @close="open = false" @after-open-change="completed" @resize="size => console.log(size)">
    <button @click="drawer?.focus()">Focus drawer root</button>
  </Drawer>
</template>
```

当前未发布开发版直接将 `:after-open-change="fn"` 迁为 `@after-open-change="fn"`（`h()` 使用 `onAfterOpenChange`），将 `:resizable="{ onResize, onResizeStart, onResizeEnd }"` 迁为 `resizable` 与三个同名事件。删除未消费的 `DrawerResizableConfig`、`panelRef` 和 `destroyInactivePanel`；元素访问改用 `DrawerRef`，销毁使用 `destroyOnHidden`。PurePanel 类型不再声称消费内部 `ariaId`、`size` 或 `contentWrapperStyle`。原先误落面板的原生 class/style 直接移到根，面板定制改用 section 语义字段。本组无兼容层或弃用期；表中的既有样式和销毁别名仍保留。

## Theme（Component Token）

4 个（CSS 变量 `--apollo-drawer-*`）：`zIndexPopup`（= `zIndexPopupBase` = **1000，不加偏移**）/
`footerPaddingBlock`(8) / `footerPaddingInline`(16) / `draggerSize`(4)。

Drawer 和 PurePanel 读取当前 `ConfigProvider.components.drawer` 的 className/style、classNames/styles 及适用的 closable/mask/focusable；实例语义样式覆盖 Provider，原生根 style 最后覆盖。四个 Token 通过 `theme.components.Drawer` 配置，已消费的主题别名、嵌套、整对象替换和撤除都会更新当前根的 CSS 变量；显式 zIndex 仍优先。`component-token` 与 `config-provider` Demo 可直接切换观察。

## 设计说明

### 尺寸轴随方位切换

`left`/`right` 用 **width**，`top`/`bottom` 用 **height**；`size` 预设 `'large'` = 736、
`'default'` = 378。⚠️ rc 的 378 兜底**只对水平方位生效**，垂直方位的默认值来自 `defaultSize`。

### 嵌套抽屉的推挤链

每个打开的子抽屉独立登记推挤；只有全部关闭或卸载后父级复位。父级按方位 `translate`（`push.distance` 默认 180，支持 CSS 长度字符串）。
**顶层抽屉自己不会位移** —— `push` 只决定距离。

### 样式引入

```ts
import '@apollo-design/theme/dist/tokens.css';  // 主题变量，必须先引
import '@apollo-design/ui/drawer/style.css';    // 按需
// 或
import '@apollo-design/ui/style.css';           // 汇总
```


## basic-right (basic-right)

基础抽屉，点击触发按钮抽屉从右滑出，点击遮罩区关闭。

### basic-right.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic-right.tsx
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Button type="primary" @click="showDrawer">Open</Button>
  <Drawer title="Basic Drawer" :open="open" @close="onClose">
    <p>Some contents...</p>
    <p>Some contents...</p>
    <p>Some contents...</p>
  </Drawer>
</template>
```

## closable-placement (closable-placement)

关闭按钮位置。

### closable-placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/closable-placement.tsx
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Button type="primary" @click="showDrawer">Open</Button>
  <Drawer title="关闭按钮位置" :open="open" @close="onClose">
    <p>Some contents...</p>
  </Drawer>
</template>
```

## component-token (component-token)

打开后切换四个组件 Token，实时观察底部间距、拖拽手柄和层级。

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, Drawer } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const open = ref(false);
const custom = ref(false);
const theme = computed(() =>
  custom.value
    ? {
        components: {
          Drawer: {
            footerPaddingBlock: 20,
            footerPaddingInline: 32,
            draggerSize: 10,
            zIndexPopup: 1400,
          },
        },
      }
    : {},
);
</script>

<template>
  <Button type="primary" @click="open = true">Open themed drawer</Button>
  <ConfigProvider :theme="theme">
    <Drawer title="Current component tokens" :open="open" resizable @close="open = false">
      <Button @click="custom = !custom">{{ custom ? 'Use defaults' : 'Override four tokens' }}</Button>
      <p>Footer padding, resize handle and stacking use the current Drawer theme.</p>
      <template #footer>Footer spacing changes immediately.</template>
    </Drawer>
  </ConfigProvider>
</template>
```

## config-provider (config-provider)

打开后切换 ConfigProvider 配置，观察关闭按钮、正文间距和底部样式跟随替换或撤除。

### config-provider.vue

```vue
<script setup lang="ts">
import {
  Button,
  ConfigProvider,
  type ConfigProviderProps,
  Drawer,
  type DrawerClosable,
} from '@apollo-design/ui';
import { computed, ref } from 'vue';

const open = ref(false);
const configured = ref(true);
const closable: DrawerClosable = { placement: 'end', 'aria-label': 'Dismiss drawer' };
const components = computed((): NonNullable<ConfigProviderProps['components']> => {
  if (!configured.value) return {};
  return {
    drawer: {
      closable,
      styles: { body: { padding: '32px' }, footer: { background: '#f5f5f5' } },
    },
  };
});
</script>

<template>
  <Button type="primary" @click="open = true">Open configured drawer</Button>
  <ConfigProvider :components="components">
    <Drawer title="Current provider configuration" :open="open" @close="open = false">
      <Button @click="configured = !configured">{{ configured ? 'Remove configuration' : 'Apply configuration' }}</Button>
      <p>The close button placement and body spacing follow provider replacement.</p>
      <template #footer>Provider footer styles</template>
    </Drawer>
  </ConfigProvider>
</template>
```

## extra (extra)

通过 `extra` slot 可以设置标题栏右侧的操作区。

### extra.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/extra.tsx —— extra 区（本仓用 `#extra` slot，值是 vnode）

import type { DrawerPlacement } from '@apollo-design/ui';
import { Button, Drawer, Radio, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const placement = ref<DrawerPlacement>('right');
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Space wrap>
    <Radio.Group v-model:value="placement">
      <Radio value="top">top</Radio>
      <Radio value="right">right</Radio>
      <Radio value="bottom">bottom</Radio>
      <Radio value="left">left</Radio>
    </Radio.Group>
    <Button type="primary" @click="showDrawer">Open</Button>
  </Space>
  <Drawer title="Drawer Title" :placement="placement" :open="open" @close="onClose">
    <p>Some contents...</p>
    <template #extra>
      <Space wrap>
        <Button>Cancel</Button>
        <Button type="primary">Submit</Button>
      </Space>
    </template>
  </Drawer>
</template>
```

## form-in-drawer (form-in-drawer)

在抽屉中填写姓名与邮箱，通过底部操作区提交。必填和邮箱格式由 Form 校验；校验失败保留输入，成功后关闭并显示本地提交结果。取消或关闭后重新打开，会清空草稿与校验信息。

### form-in-drawer.vue

```vue
<script setup lang="ts">
import { Alert, Button, Drawer, Form, FormItem, Input, useForm } from '@apollo-design/ui';
import { ref, useId } from 'vue';

const [form] = useForm();
const formId = `drawer-contact-${useId()}`;
const open = ref(false);
const submitted = ref('');
const initialValues = { name: '', email: '' };

function showDrawer() {
  form.resetFields();
  submitted.value = '';
  open.value = true;
}

function handleFinish(values: Record<string, unknown>) {
  submitted.value = `${values.name} · ${values.email}`;
  open.value = false;
}
</script>

<template>
  <div class="contact-form-demo">
    <Button type="primary" @click="showDrawer">新建联系人</Button>
    <Alert v-if="submitted" type="success" show-icon title="示例提交成功" :description="submitted" />
  </div>
  <Drawer title="新建联系人" size="min(100%, 520px)" :open="open" @close="open = false">
    <Form
      :id="formId"
      :name="formId"
      :form="form"
      :initial-values="initialValues"
      layout="vertical"
      novalidate
      @finish="handleFinish"
    >
      <FormItem label="姓名" name="name" :rules="[{ required: true, whitespace: true, message: '请输入姓名' }]">
        <Input aria-label="姓名" autocomplete="name" placeholder="请输入姓名" />
      </FormItem>
      <FormItem
        label="邮箱"
        name="email"
        :rules="[
          { required: true, message: '请输入邮箱' },
          { type: 'email', message: '请输入有效的邮箱地址' },
        ]"
      >
        <Input aria-label="邮箱" type="email" autocomplete="email" placeholder="name@example.com" />
      </FormItem>
    </Form>
    <template #footer>
      <div class="contact-form-actions">
        <Button class="contact-form-cancel" @click="open = false">取消</Button>
        <Button type="primary" html-type="submit" :form="formId">提交</Button>
      </div>
    </template>
  </Drawer>
</template>

<style scoped>
.contact-form-demo {
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 12px;
}
.contact-form-actions {
  display: flex;
  justify-content: flex-end;
  gap: 8px;
}
</style>
```

## loading (loading)

抽屉内容加载中。

### loading.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/loading.tsx
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Button type="primary" @click="showDrawer">Open</Button>
  <Drawer title="抽屉内容加载中" :open="open" @close="onClose">
    <p>Some contents...</p>
  </Drawer>
</template>
```

## mask (mask)

遮罩模糊。

### mask.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/mask.tsx
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Button type="primary" @click="showDrawer">Open</Button>
  <Drawer title="遮罩模糊" :open="open" @close="onClose">
    <p>Some contents...</p>
  </Drawer>
</template>
```

## multi-level-drawer (multi-level-drawer)

嵌套抽屉：打开子抽屉时父级会被推挤（`DrawerContext` 的 push/pull 链）。

### multi-level-drawer.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/multi-level-drawer.tsx —— 嵌套抽屉（父级被推挤）
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const childrenDrawer = ref(false);
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
const showChildrenDrawer = () => {
  childrenDrawer.value = true;
};
const onChildrenDrawerClose = () => {
  childrenDrawer.value = false;
};
</script>

<template>
  <Button type="primary" @click="showDrawer">Open drawer</Button>
  <Drawer title="Multi-level drawer" :open="open" @close="onClose">
    <Button type="primary" @click="showChildrenDrawer">Two-level drawer</Button>
    <Drawer title="Two-level Drawer" :open="childrenDrawer" @close="onChildrenDrawerClose">
      <p>This is two-level drawer</p>
    </Drawer>
  </Drawer>
</template>
```

## no-mask (no-mask)

不显示遮罩。

### no-mask.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/no-mask.tsx
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Button type="primary" @click="showDrawer">Open</Button>
  <Drawer title="不显示遮罩" :open="open" @close="onClose">
    <p>Some contents...</p>
  </Drawer>
</template>
```

## placement (placement)

自定义位置，点击触发按钮抽屉从相应的位置滑出，点击遮罩区关闭。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/placement.tsx —— 四个方位

import type { DrawerPlacement } from '@apollo-design/ui';
import { Button, Drawer, Radio, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const placement = ref<DrawerPlacement>('left');
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Space wrap>
    <Radio.Group v-model:value="placement">
      <Radio value="top">top</Radio>
      <Radio value="right">right</Radio>
      <Radio value="bottom">bottom</Radio>
      <Radio value="left">left</Radio>
    </Radio.Group>
    <Button type="primary" @click="showDrawer">Open</Button>
  </Space>
  <Drawer title="Basic Drawer" :placement="placement" :open="open" @close="onClose">
    <p>Some contents...</p>
  </Drawer>
</template>
```

## render-in-current (render-in-current)

`getContainer={false}` 时抽屉**不 portal**，渲染在当前节点里（需要自己定位父容器）。

### render-in-current.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/render-in-current.tsx —— getContainer=false 内联渲染（不 portal）
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <div style="position: relative; height: 240px; overflow: hidden; border: 1px solid var(--apollo-color-border)">
    <Button type="primary" @click="showDrawer">Open</Button>
    <Drawer
      title="Render in current node"
      :get-container="false"
      :open="open"
      :style="{ position: 'absolute' }"
      @close="onClose"
    >
      <p>Render in current node (no portal).</p>
    </Drawer>
  </div>
</template>
```

## render-panel (render-panel)

调试用面板。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/render-panel.tsx
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Button type="primary" @click="showDrawer">Open</Button>
  <Drawer title="调试用面板" :open="open" @close="onClose">
    <p>Some contents...</p>
  </Drawer>
</template>
```

## resizable (resizable)

可拖拽调整尺寸的抽屉（`resizable`），使用 `resize` / `resizeStart` / `resizeEnd` 事件显示当前尺寸，并用 `maxSize` 限制上界。

### resizable.vue

```vue
<script setup lang="ts">
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const size = ref(378);
const dragging = ref(false);
function start(value: number) {
  dragging.value = true;
  size.value = value;
}
function end(value: number) {
  dragging.value = false;
  size.value = value;
}
</script>

<template>
  <Button type="primary" @click="open = true">Open resizable drawer</Button>
  <Drawer
    title="Resizable Drawer"
    resizable
    :max-size="600"
    :open="open"
    @close="open = false"
    @resize="value => size = value"
    @resize-start="start"
    @resize-end="end"
  >
    <p>Drag the edge to resize (up to 600px).</p>
    <p aria-live="polite">{{ dragging ? 'Resizing' : 'Current size' }}: {{ Math.round(size) }}px</p>
  </Drawer>
</template>
```

## scroll-debug (scroll-debug)

长内容滚动。

### scroll-debug.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/scroll-debug.tsx
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Button type="primary" @click="showDrawer">Open</Button>
  <Drawer title="长内容滚动" :size="'50%'" :open="open" @close="onClose">
    <p>Some contents...</p>
  </Drawer>
</template>
```

## size (size)

抽屉尺寸，可选 `default`（378px）与 `large`（736px）。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/size.tsx —— default / large 预设
import { Button, Drawer, Radio, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const size = ref<'default' | 'large'>('default');
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Space wrap>
    <Radio.Group v-model:value="size">
      <Radio value="default">Default</Radio>
      <Radio value="large">Large</Radio>
    </Radio.Group>
    <Button type="primary" @click="showDrawer">Open</Button>
  </Space>
  <Drawer title="Basic Drawer" :size="size" :open="open" @close="onClose">
    <p>Some contents...</p>
  </Drawer>
</template>
```

## style-class (style-class)

语义化样式。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx
import { Button, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const showDrawer = () => {
  open.value = true;
};
const onClose = () => {
  open.value = false;
};
</script>

<template>
  <Button type="primary" @click="showDrawer">Open</Button>
  <Drawer title="语义化样式" :open="open" @close="onClose">
    <p>Some contents...</p>
  </Drawer>
</template>
```

## user-profile (user-profile)

在抽屉中使用 Avatar 与 Descriptions 分组展示示例用户的基本资料和工作信息。面板适应可用宽度，可通过底部按钮或抽屉关闭按钮关闭，再次打开仍展示同一份静态资料。

### user-profile.vue

```vue
<script setup lang="ts">
import { Avatar, Button, Descriptions, Divider, Drawer } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const personal = [
  { key: 'name', label: '姓名', children: '林晓' },
  { key: 'email', label: '邮箱', children: 'lin@example.com' },
  { key: 'city', label: '城市', children: '杭州' },
];
const work = [
  { key: 'role', label: '职位', children: '产品设计师' },
  { key: 'team', label: '部门', children: '设计团队' },
  { key: 'joined', label: '加入时间', children: '2024-03-01' },
];
</script>

<template>
  <Button @click="open = true">查看用户资料</Button>
  <Drawer title="用户资料" size="min(100%, 520px)" :open="open" @close="open = false">
    <div class="profile-heading">
      <Avatar :size="64">林</Avatar>
      <div>
        <h3>林晓</h3>
        <p>产品设计师 · 设计团队</p>
      </div>
    </div>
    <Descriptions title="基本信息" :column="1" :items="personal" />
    <Divider />
    <Descriptions title="工作信息" :column="1" :items="work" />
    <template #footer>
      <div class="profile-footer">
        <Button class="profile-close" @click="open = false">关闭资料</Button>
      </div>
    </template>
  </Drawer>
</template>

<style scoped>
.profile-heading {
  display: flex;
  align-items: center;
  gap: 16px;
  margin-bottom: 24px;
}
.profile-heading h3 {
  margin: 0 0 4px;
}
.profile-heading p {
  margin: 0;
}
.profile-footer {
  display: flex;
  justify-content: flex-end;
}
</style>
```

---

# Dropdown

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/dropdown


将一组操作收纳到触发元素下的菜单。菜单的数据、选择与键盘导航由 Menu 提供；自定义浮层使用具名槽。

## 代码演示

见 demo/ 中的现有示例。DropdownButton 是 Apollo 当前支持的按钮组合。

## Dropdown Props

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| menu | 当前 MenuProps；items、选择与事件继续由 Menu 拥有 | — |
| open / defaultOpen | `v-model:open` 受控值 / 非受控初值 | false |
| trigger | click、hover、contextMenu 的数组；优先于 Provider | hover |
| disabled | 禁止触发；未指定时读取全局 disabled，显式 false 可覆盖 | — |
| placement | DropdownPlacement；Center 旧值归一为 top/bottom | bottomLeft，RTL 为 bottomRight |
| arrow | boolean 或 `{ pointAtCenter }` | false |
| mouseEnterDelay / mouseLeaveDelay | 当前延迟，单位秒 | 0.15 / 0.1 |
| autoAdjustOverflow | 自动调整溢出 | true |
| getPopupContainer | 实际浮层容器，支持 HTMLElement / ShadowRoot；未指定时使用 Provider | body |
| destroyOnHidden / forceRender | 离场完成后销毁 / 预渲染 | false |
| transitionName | 覆盖已有方向动画名 | 按 placement 选择 |
| zIndex | 显式数值层级，0 合法 | 当前组件 Token 或父层级加偏移 |
| classNames / styles | root、item、itemTitle、itemIcon、itemContent；静态对象或 `({ props }) => 对象` | — |
| rootClassName / overlayClassName / overlayStyle / destroyPopupOnHide | 保留已有别名；优先使用语义字段与 destroyOnHidden | — |

函数式语义字段读取当前解析后的配置与开合状态。root 属于真正的浮层根；四个 item 字段传到真实 Menu 区域，与 menu.classNames/styles 合并，Dropdown 字段覆盖同名样式。样式值使用 Vue CSSProperties，包括 undefined 和自定义 CSS 属性。

原生 class/style、id、ARIA 与原生事件属于触发元素。单个元素或组件保持原节点；文本、多节点和 Fragment 内容由稳定 span 承载。浮层外观使用 styles.root/classNames.root。Provider 的 class/style/语义配置、arrow、trigger、延迟与全局容器读取当前值。

## 事件

| 事件 | 载荷 |
| --- | --- |
| update:open | `(open: boolean)` |
| openChange | `(open: boolean, info: { source: 'trigger' 或 'menu' })` |
| afterOpenChange | `(open: boolean)`，实际显隐动画结束后 |

支持 Vue listener 数组、替换与 `.once`。菜单选择时每个通知只发一次；selectable 且 multiple 的菜单保留打开。受控关闭是提议，父级拒绝后仍保持当前值，撤控保留最后接受值。旧 `:after-open-change="fn"` 直接改为 `@after-open-change="fn"`（h/JSX 使用 onAfterOpenChange），无兼容回调通道。

## 插槽与引用

| 插槽 | 参数 / 行为 |
| --- | --- |
| default | 完整触发内容 |
| popupRender | `{ originNode: VNodeChild }`；当前槽存在则优先，空内容不恢复菜单 |

DropdownRef 保留 `forceAlign()`、`nativeElement()`、`popupElement()`。后两者返回当前实际 HTMLElement 或 null；关闭后的保留 DOM 由 destroyOnHidden 决定。

## DropdownButton

保留 split、type、size、loading、danger、disabled、href、target、menu、placement、trigger、arrow、open、容器和层级配置。非 split 时主钮是触发器；split 时主钮只发 click，右钮独立开菜单。target 作用于主链接，原生 class/style/其他 attrs 作用于组根。

事件为 click(MouseEvent)、openChange(open, info) 和 update:open；支持 v-model:open。默认槽承载完整主钮内容；icon 槽在当前 render 读取并保留所有节点，存在但为空时隐藏默认图标。buttonsRender 接收 `{ buttons: [主钮 VNode, 触发钮 VNode] }`，输出两个对应的 Vue 子节点；popupRender 与 Dropdown 同型。DropdownButtonRef 保留 nativeElement()，指向实际下拉触发元素。

旧 icon 函数/prop 通道已迁为 #icon；类型不再保留未消费的 icon 字段。Dropdown.Button 与 Dropdown._InternalPanelDoNotUseOrYouWillBeFired 继续是具备实际组件类型的静态别名。

## PurePanel 与主题

DropdownPurePanel 在文档流中展示同一 Menu，接受 menu、classNames/styles、popupRender 槽与原生 class/style。原生样式支持字符串、对象和数组，优先于语义根样式；当前 Provider 与主题同步作用于面板。

已有七个 CSS 字段包括 zIndexPopup（默认 1050）、paddingBlock（默认 5）以及 arrowOffsetHorizontal、arrowOffsetVertical、arrowShadowWidth、arrowPath、arrowPolygon。当前主题的 marginXXS、sizePopupArrow 和 borderRadius 同时供 CSS 与定位使用。嵌套和显式层级使用已有数值协议；非数值 CSS 表达式保留样式，但不参与自动后代数值层级计算。


## arrow (arrow)

可以支持箭头。

### arrow.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/arrow.tsx
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
];

const placements = ['bottomLeft', 'bottom', 'bottomRight', 'topLeft', 'top', 'topRight'] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 8px; height: 200px; align-content: center">
    <Dropdown v-for="p in placements" :key="p" :menu="{ items }" :placement="p" arrow>
      <Button>{{ p }}</Button>
    </Dropdown>
  </div>
</template>
```

## arrow-center (arrow-center)

设置箭头指向目标元素中心。

### arrow-center.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/arrow-center.tsx
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
];

const placements = ['bottomLeft', 'bottom', 'bottomRight', 'topLeft', 'top', 'topRight'] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 8px; height: 200px; align-content: center">
    <Dropdown v-for="p in placements" :key="p" :menu="{ items }" :placement="p" :arrow="{ pointAtCenter: true }">
      <Button>{{ p }}</Button>
    </Dropdown>
  </div>
</template>
```

## basic (basic)

鼠标移入，出现下拉菜单。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic.tsx
import { DownOutlined, SmileOutlined } from '@apollo-design/icons';
import { Button, Dropdown } from '@apollo-design/ui';
import { h } from 'vue';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item (disabled)', icon: h(SmileOutlined), disabled: true },
  { key: '3', label: '3rd menu item' },
];
</script>

<template>
  <Dropdown :menu="{ items }">
    <Button type="link">
      Hover me
      <DownOutlined />
    </Button>
  </Dropdown>
</template>
```

## context-menu (context-menu)

默认是鼠标移入触发菜单，可以设置成鼠标右击触发。

### context-menu.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/context-menu.tsx
import { Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
];
</script>

<template>
  <Dropdown :menu="{ items }" :trigger="['contextMenu']">
    <div style="padding: 40px; border: 1px dashed var(--apollo-color-border); text-align: center; user-select: none">
      Right Click on here
    </div>
  </Dropdown>
</template>
```

## custom-dropdown (custom-dropdown)

使用 popupRender 对菜单进行扩展。

### custom-dropdown.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/custom-dropdown.tsx。C8-R2：popupRender 走 `#popupRender="{ originNode }"` 插槽。
import { Button, Dropdown } from '@apollo-design/ui';
</script>

<template>
  <Dropdown>
    <template #popupRender="{ originNode }">
      <div style="padding: 8px; width: 200px">
        <component :is="originNode" />
        <div style="border-top: 1px solid var(--apollo-color-border-secondary); padding-top: 8px; margin-top: 4px">
          This is a custom dropdown content.
        </div>
      </div>
    </template>
    <Button type="link">
      Hover me
    </Button>
  </Dropdown>
</template>
```

## dropdown-button (dropdown-button)

左边是按钮，右边是额外的相关功能菜单。

### dropdown-button.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/dropdown-button.tsx
import { DropdownButton } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
  { key: '3', label: '3rd item' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; align-items: flex-start">
    <DropdownButton :menu="{ items }">
      Dropdown
    </DropdownButton>
    <DropdownButton :menu="{ items }" placement="top">
      Dropdown
    </DropdownButton>
    <DropdownButton :menu="{ items }" disabled>
      Dropdown
    </DropdownButton>
    <DropdownButton :menu="{ items }" :trigger="['click']">
      Dropdown
    </DropdownButton>
    <DropdownButton :menu="{ items }" split>
      Dropdown
    </DropdownButton>
  </div>
</template>
```

## event (event)

点击菜单项后会触发事件。

### event.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/event.tsx
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
  { key: '3', label: '3rd menu item' },
];

const onClick = ({ key }: { key: string | number }) => {
  console.log(`Click on item ${key}`);
};
</script>

<template>
  <Dropdown :menu="{ items, onClick }">
    <Button type="link">
      Hover me
    </Button>
  </Dropdown>
</template>
```

## extra (extra)

支持附加的节点展示（extra）。

### extra.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/extra.tsx
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item', extra: '⌘P' },
  { key: '2', label: '2nd menu item', extra: '⌘N' },
];
</script>

<template>
  <Dropdown :menu="{ items }">
    <Button type="link">
      Hover me
    </Button>
  </Dropdown>
</template>
```

## item (item)

默认是 hover 触发菜单，菜单项支持 disabled。

### item.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/item.tsx
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '0', label: '1st menu item' },
  { key: '1', label: '2nd menu item' },
  { key: '3', label: '3rd menu item', disabled: true },
];
</script>

<template>
  <Dropdown :menu="{ items }">
    <Button type="link">
      Hover me
    </Button>
  </Dropdown>
</template>
```

## loading (loading)

加载中的状态下展示下拉菜单。

### loading.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/loading.tsx
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
];
</script>

<template>
  <Dropdown :menu="{ items }">
    <Button loading>
      Loading
    </Button>
  </Dropdown>
</template>
```

## menu-full (menu-full)

menu 属性的完整能力（danger/divider/disabled）。

### menu-full.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/menu-full.tsx（menu 的完整 props 通道）
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item', danger: true },
  { type: 'divider' as const },
  { key: '3', label: '3rd menu item', disabled: true },
];
</script>

<template>
  <Dropdown :menu="{ items, selectable: true, onClick: (i: unknown) => console.log(i) }">
    <Button type="link">
      Hover me
    </Button>
  </Dropdown>
</template>
```

## overlay-open (overlay-open)

受控 open 的展示。

### overlay-open.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/overlay-open.tsx（受控 open）
import { Button, Dropdown } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(true);

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
];

const toggle = () => {
  open.value = !open.value;
};
</script>

<template>
  <Dropdown :menu="{ items }" :open="open" @open-change="(v: boolean) => (open = v)">
    <Button @click="toggle">
      Toggle open
    </Button>
  </Dropdown>
</template>
```

## placement (placement)

按钮有六个 placement 选项。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/placement.tsx（12 方向网格）
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
];

const placements = ['bottomLeft', 'bottom', 'bottomRight', 'topLeft', 'top', 'topRight'] as const;

const grid: Array<Array<(typeof placements)[number] | ''>> = [
  ['', placements[0], placements[1], placements[2], ''],
  [placements[3], '', '', '', placements[4]],
  [placements[5], '', '', '', ''],
];
void grid;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 8px; height: 200px; align-content: center">
    <Dropdown v-for="p in placements" :key="p" :menu="{ items }" :placement="p">
      <Button>{{ p }}</Button>
    </Dropdown>
  </div>
</template>
```

## render-panel (render-panel)

DropdownPurePanel 在文档流中展示同一个菜单组合；支持当前主题和原生 class/style。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/render-panel.tsx（PurePanel 静态面板）
import { DropdownPurePanel } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item', danger: true },
  { key: '3', label: '3rd menu item', disabled: true },
];
</script>

<template>
  <div style="margin: 24px">
    <DropdownPurePanel :menu="{ items }" />
  </div>
</template>
```

## selectable (selectable)

菜单项可选择。

### selectable.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/selectable.tsx
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
];
</script>

<template>
  <Dropdown :menu="{ items, selectable: true, defaultSelectedKeys: ['1'] }">
    <Button type="link">
      Hover me
    </Button>
  </Dropdown>
</template>
```

## selection (selection)

多选的菜单项。

### selection.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/selection.tsx
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
];
</script>

<template>
  <Dropdown :menu="{ items, selectable: true, multiple: true }">
    <Button type="link">
      Hover me
    </Button>
  </Dropdown>
</template>
```

## style-class (style-class)

浮层根与菜单内容使用各自的 classNames/styles；切换当前主题的菜单间距与层级。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx（classNames/styles 语义槽）
import { Button, ConfigProvider, Dropdown, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const custom = ref(true);

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
];
</script>

<template>
  <ConfigProvider :theme="custom ? { components: { Dropdown: { paddingBlock: 9, zIndexPopup: 1500 } } } : undefined">
    <Space wrap>
    <Button @click="custom = !custom">Change menu spacing</Button>
    <Dropdown
    :menu="{ items }"
    :class-names="{ root: 'my-root' }"
    :styles="{ root: { minWidth: '200px' }, itemContent: { letterSpacing: '1px' } }"
    :trigger="['click']"
  >
      <Button>Open styled actions</Button>
    </Dropdown>
    </Space>
  </ConfigProvider>
</template>
```

## sub-menu (sub-menu)

传入的菜单里有子菜单。

### sub-menu.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/sub-menu.tsx
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  {
    key: '1',
    label: '1st menu item',
    children: [
      { key: '1-1', label: '1st sub menu item' },
      { key: '1-2', label: '2nd sub menu item' },
    ],
  },
  {
    key: '2',
    label: '2nd menu item',
    children: [
      { key: '2-1', label: '1st sub menu item' },
      { key: '2-2', label: '2nd sub menu item' },
    ],
  },
];
</script>

<template>
  <Dropdown :menu="{ items }">
    <Button type="link">
      Hover me
    </Button>
  </Dropdown>
</template>
```

## trigger (trigger)

支持点击、右键触发。

### trigger.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/trigger.tsx
import { DownOutlined } from '@apollo-design/icons';
import { Button, Dropdown } from '@apollo-design/ui';

const items = [
  { key: '1', label: '1st menu item' },
  { key: '2', label: '2nd menu item' },
];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <Dropdown :menu="{ items }" :trigger="['click']">
      <Button type="link">
        Click me
        <DownOutlined />
      </Button>
    </Dropdown>
    <Dropdown :menu="{ items }" :trigger="['contextMenu']">
      <div style="padding: 24px; border: 1px dashed var(--apollo-color-border); user-select: none">
        Right Click on here
      </div>
    </Dropdown>
  </div>
</template>
```

---

# Empty

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/empty


数据为空时的占位提示。默认插槽可放置新建按钮等引导内容。

## 何时使用

- 列表、表格或业务区域没有数据时显示说明。
- 使用完整图片、描述和页脚插槽承载业务内容。

## 代码演示

六个示例覆盖默认与简洁插画、自定义内容、当前 Provider 配置、条件描述和四个语义区域。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | 完整组件前缀 | `string` | `apollo-empty`，跟随 ConfigProvider |
| image | 顶层字符串为图片 URL；也支持组件、VNode、数组及数字。只有 undefined 回退；null、布尔值、空串及空内容隐藏图片宿主 | `EmptyImage` | Provider 配置或 `PRESENTED_IMAGE_DEFAULT` |
| imageStyle | 既有弃用字段，使用 `styles.image`；合并后后者优先 | `CSSProperties` | — |
| description | 完整 Vue 内容；只有 undefined 使用当前语言；空内容隐藏描述宿主，数字 0 保留 | `VNodeChild` | 当前 locale 的 `Empty.description` |
| classNames | 四个语义区域的类名，函数接收当前局部 Props | `EmptySemanticValue<EmptySemanticClassNames>` | — |
| styles | 四个语义区域的样式，函数接收当前局部 Props | `EmptySemanticValue<EmptySemanticStyles>` | — |

根节点支持 Vue 原生 class、style、dir、data/ARIA 和事件 attrs。style 接受字符串、对象和数组；原生 style 覆盖 `styles.root`。组件没有业务 Emits 或 v-model。

### 插槽

| 名称 | 说明 |
|---|---|
| image | 完整图片区域，优先于 image 和 Provider 图片；自定义内容按自然高度布局 |
| description | 完整描述区域，优先于 description 和语言默认值 |
| default | 完整页脚区域，例如一个或多个操作控件 |

三个插槽均在当前 render 中求值一次；存在即优先，故意返回空内容时也不回退。空数组、注释、布尔值及空 Fragment 不创建带间距的空宿主。完整业务子级保持自身属性、编辑状态和焦点。

### Provider 与语义区域

`ConfigProvider :components="{ empty }"` 接收 `EmptyConfig`，包含 `image`、`className`、`style`、`classNames`、`styles`，支持动态更新和移除。Provider 的语义配置为对象。

四个区域为 `root`、`image`、`description`、`footer`。类名按 Provider、局部语义、原生根 class 合并；根样式按以下顺序覆盖：

```
Provider styles.root → Provider style → 局部 styles.root → 原生根 style
```

其余区域由局部语义覆盖 Provider 语义；`imageStyle` 低于 `styles.image`。图像高度与透明度仅作用于内置插画和 URL 图片，自定义完整内容保留自身布局与颜色。RTL 跟随当前 Provider，原生 dir 可覆盖。

### 静态属性、类型与 ref

`Empty.PRESENTED_IMAGE_DEFAULT` 和 `Empty.PRESENTED_IMAGE_SIMPLE` 也提供同名具名导出，根入口与 `@apollo-design/ui/empty` 的值相同。它们是可复用组件定义；简洁组件及其 VNode 会使用 normal 模式，相似的自建图形不会触发此模式。

导出类型：`EmptyProps`、`EmptySlots`、`EmptyImage`、`EmptyRef`、`EmptyConfig`、`EmptySemanticClassNames`、`EmptySemanticStyles`、`EmptySemanticValue`、`EmptySemanticType`、`EmptySemanticAllType`。

| Expose | 类型 | 说明 |
|---|---|---|
| nativeElement | `HTMLDivElement \| null` | 实际根 div；挂载前及卸载后为空 |

URL 图片 alt 使用字符串 description；非字符串使用当前语言的空状态说明。内置插画的 title 随语言更新，纯图片状态仍有可访问名称。

### 主题与样式

Empty 没有 Component Token。布局消费现有 Alias Token；插画调色在运行时从当前主题派生，保留生成几何与来源。默认说明文字使用 `colorTextSecondary`。

```ts
import '@apollo-design/theme/tokens.css';
import '@apollo-design/ui/empty/style.css';
// 或 import '@apollo-design/ui/style.css';
```

静态 CSS 只包含 apollo 根前缀。自定义根前缀 my-app 时，使用 `ConfigProvider prefix-cls="my-app"` 并加载 `genComponentCss('empty', 'my-app')` 生成的样式。直接设置组件 `prefixCls` 时传完整值，例如 my-app-empty。


## 基础 (basic)

最简单的用法：默认插画 + 默认描述（来自 locale，`en_US` 是 `No data`）。

### basic.vue

```vue
<script setup lang="ts">
import { Empty } from '@apollo-design/ui';
</script>

<template>
  <Empty />
</template>
```

## 简洁 (simple)

`PRESENTED_IMAGE_SIMPLE` 是模块级常量，传给 `image` 后根元素会多出 `-normal` 类名
（高度与间距随之变化）。判据是**引用相等**，不是「长得像不像」。

### simple.vue

```vue
<script setup lang="ts">
import { Empty, PRESENTED_IMAGE_SIMPLE } from '@apollo-design/ui';
</script>

<template>
  <Empty :image="PRESENTED_IMAGE_SIMPLE" description="No data" />
</template>
```

## 自定义插画 (customize)

使用原生 #image 插槽放入完整图形、编辑器和后续内容。自定义内容使用自然高度，更新配置时编辑草稿与焦点保持。存在的空插槽也优先于 image 默认值。

image 数据仍接受 URL、VNode、组件定义、数组和数字；组件定义需提供正常的 render 或预编译模板。

### customize.vue

```vue
<script setup lang="ts">
import { Empty, Input } from '@apollo-design/ui';
import { ref } from 'vue';

const draft = ref('');
</script>

<template>
  <Empty description="Custom image">
    <template #image>
      <svg width="64" height="41" viewBox="0 0 64 41" role="img" aria-label="Custom diagram">
        <ellipse fill="var(--apollo-color-fill-tertiary)" cx="32" cy="33" rx="32" ry="7" />
        <text x="32" y="26" text-anchor="middle" font-size="12" fill="var(--apollo-color-text)">custom</text>
      </svg>
      <label class="empty-draft">
        Draft name
        <Input v-model:value="draft" placeholder="Keep editing while configuration changes" />
      </label>
      <span>Complete image content</span>
    </template>
  </Empty>
</template>

<style scoped>
.empty-draft { display: block; margin-block: 8px; }
.empty-draft :deep(.apollo-input) { max-width: 100%; }
</style>
```

## 自定义描述 (description)

保留字符串描述、关闭描述和完整节点三个场景。#description 可以包含多个业务节点；复选框切换槽内内容，故意为空时不回退到描述 prop，也不产生带间距的空宿主。

只有 description 为 undefined 才使用当前语言。false、null、空串和空数组隐藏描述，数字 0 保留。

### description.vue

```vue
<script setup lang="ts">
import { Checkbox, Empty } from '@apollo-design/ui';
import { ref } from 'vue';

const showDescription = ref(true);
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Empty description="Nothing to show" />
    <Empty :description="false" />
    <Checkbox v-model:checked="showDescription">Show description slot</Checkbox>
    <Empty description="The slot suppresses this fallback even when empty">
      <template #description>
        <template v-if="showDescription">
          <span>描述可以是任意节点，例如 </span><a class="empty-description-link" href="#demo-description">这段链接</a><strong>，以及后续内容。</strong>
        </template>
      </template>
    </Empty>
  </div>
</template>

<style scoped>
.empty-description-link { color: inherit; text-decoration: underline; }
</style>
```

## 全局配置 (config-provider)

真实 ConfigProvider 通过 components.empty 提供 image、className、style、classNames 和 styles。勾选控件切换当前配置；示例保留 URL 图片输入，使用本地确定素材，支持离线访问。

组件的 image 优先于 Provider；只有 undefined 才回退。

### config-provider.vue

```vue
<script setup lang="ts">
import {
  Checkbox,
  ConfigProvider,
  Empty,
  type EmptyConfig,
  PRESENTED_IMAGE_SIMPLE,
} from '@apollo-design/ui';
import { computed, ref } from 'vue';

const custom = ref(false);
// A deterministic original illustration keeps the URL-image example available offline.
const image = `data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="120" height="80" viewBox="0 0 120 80"><rect x="20" y="24" width="80" height="42" rx="8" fill="#8ba6bf"/><path d="M44 24V14h32v10M44 45h32" fill="none" stroke="#18344d" stroke-width="4"/></svg>')}`;
const empty = computed<EmptyConfig>(() => ({
  image: custom.value ? image : PRESENTED_IMAGE_SIMPLE,
  className: custom.value ? 'empty-config-custom' : 'empty-config-simple',
  styles: { description: { fontWeight: custom.value ? 600 : 400 } },
}));
</script>

<template>
  <Checkbox v-model:checked="custom">Change Provider configuration</Checkbox>
  <ConfigProvider :components="{ empty }">
    <Empty description="Current illustration from ConfigProvider" />
  </ConfigProvider>
</template>
```

## 语义化类名与样式 (style-class)

classNames/styles 覆盖 root、image、description、footer 四个区域。局部函数式语义配置接收当前 props；勾选后说明文字与字重同步更新。

背景和文字使用成对的主题 Token。根样式优先级为 Provider styles.root → Provider style → 局部 styles.root → 原生根 style，其他区域由局部语义覆盖 Provider。

### style-class.vue

```vue
<script setup lang="ts">
import { Button, Checkbox, Empty, type EmptyProps } from '@apollo-design/ui';
import { ref } from 'vue';

const highlighted = ref(false);
const classNames = {
  root: 'demo-empty-root',
  image: 'demo-empty-image',
  description: 'demo-empty-description',
  footer: 'demo-empty-footer',
};
const styles: EmptyProps['styles'] = ({ props }) => ({
  root: {
    backgroundColor: 'var(--apollo-color-fill-alter)',
    color: 'var(--apollo-color-text)',
    padding: 'var(--apollo-padding)',
  },
  image: { opacity: 0.8 },
  description: { fontWeight: props.description === 'Highlighted description' ? 600 : 400 },
  footer: { paddingBlock: 'var(--apollo-padding-xs)' },
});
</script>

<template>
  <Checkbox v-model:checked="highlighted">Highlight description</Checkbox>
  <Empty
    :class-names="classNames"
    :styles="styles"
    :description="highlighted ? 'Highlighted description' : '带语义化类名与样式'"
  >
    <Button type="primary">Create</Button><span> — complete footer content</span>
  </Empty>
</template>
```

---

# Flex

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/flex


Flex 直接对完整 Vue 内容进行排列和对齐，不为每个子项增加包裹元素。需要为内联子项分别提供间距宿主时可使用 Space。

## 代码演示

六组成对 Demo 展示方向、对齐、间距、换行、响应式项目摘要和布局块。演示中的原生控件具有独立名称，保留正常键盘操作。

## API

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | 完整类名前缀；自定义前缀由调用方提供对应静态 CSS | `string` | 当前 ConfigProvider，兜底 `apollo-flex` |
| vertical | 主轴是否垂直；未传时读取当前 `flex.vertical` | `boolean` | `undefined` |
| orientation | 优先于 vertical 和 Provider 的方向 | `'horizontal' \| 'vertical'` | 最终兜底 horizontal |
| wrap | 多行排列；true 等于 wrap | `boolean \| 'wrap' \| 'nowrap' \| 'wrap-reverse'` | 单行 |
| justify | 主轴 CSS 对齐方式 | `FlexJustify` | 原生 flex-start 行为 |
| align | 交叉轴 CSS 对齐方式 | `FlexAlign` | 横向 flex-start；纵向 stretch |
| flex | CSS 简写，数字无单位 | `string \| number` | — |
| gap | 像素数字、CSS 长度或预设 | `'small' \| 'medium' \| 'middle' \| 'large' \| string \| number` | — |
| component | 原生标签，或将 attrs/default slot 转发到所属宿主的 Vue 组件 | `Component \| string` | `'div'` |

方向优先级为 `orientation` → 显式 `vertical` → 当前 ConfigProvider `flex.vertical` → horizontal。Provider 的 `flex.className`、`flex.style`、vertical、direction 和前缀均响应当前配置。显式原生 `dir` 优先于 Provider 方向。

### 插槽、事件与状态

仅提供 `#default`，支持零、文本、多个 VNode 与 Fragment 等完整 Vue 内容。没有业务 emits 或 v-model。根原生监听器接收原始 DOM 事件且只触发一次；调用方的输入、链接、按钮拥有其原生语义、焦点和键盘行为。

根 `class`、`style`、id、data/ARIA、tabindex 和监听器走 Vue attrs。style 接受字符串、对象和数组。优先级为当前主题别名 → Provider `flex.style` → 原生 `style` → `flex`/非预设 `gap` 派生值。外观更新保留宿主与业务 key 的子项；修改 `component` 按 Vue 正常替换其所属宿主。空根仍挂载，保留布局与原生语义。

### Ref

| 名称 | 类型 | 说明 |
|---|---|---|
| nativeElement | `HTMLElement \| null` | 当前唯一 HTML 宿主，含 Vue 根组件的真实元素；挂载前、卸载后或没有唯一 HTML 宿主时为 null |

自定义 Vue 组件负责自己的 attrs/slot 转发；Flex 暴露实际 HTML 宿主，不暴露组件实例。Fragment、纯文本和非 HTML 根不提供 `nativeElement`。

## Theme

Flex 没有组件 Token。small 消费当前 `paddingXS`，medium/middle 消费 `padding`，large 消费 `paddingLG`。存在 ThemeContext 时在 Flex 根作用域写入这三个别名变量，支持不全局注入的 ThemeProvider 及嵌套默认主题复位。原生 style 的自定义属性可局部覆盖别名。数字 gap 支持零与小数。


## 基本布局 (basic)

使用Apollo Radio.Group切换横向与纵向布局，子元素直接参与 Flex。

### basic.vue

```vue
<script setup lang="ts">
import { Flex, Radio } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<'horizontal' | 'vertical'>('horizontal');
const baseStyle = { width: '25%', height: '54px' };
</script>

<template>
  <Flex gap="middle" vertical>
    <fieldset style="margin: 0; padding: 0; border: 0; min-width: 0">
      <legend>Direction</legend>
      <Radio.Group v-model:value="value" :options="['horizontal', 'vertical']" />
    </fieldset>
    <Flex :vertical="value === 'vertical'">
      <div v-for="i in 4" :key="i" :style="{ ...baseStyle, background: i % 2 ? 'var(--apollo-color-primary)' : 'var(--apollo-color-primary-bg-hover)' }" />
    </Flex>
  </Flex>
</template>
```

## 对齐方式 (align)

使用原生下拉控件改变主轴与交叉轴对齐。横向默认顶部对齐，纵向默认拉伸。

### align.vue

```vue
<script setup lang="ts">
import type { FlexAlign, FlexJustify } from '@apollo-design/ui';
import { Button, Flex, Select } from '@apollo-design/ui';
import { ref } from 'vue';

const justifyOptions = [
  'flex-start',
  'center',
  'flex-end',
  'space-between',
  'space-around',
  'space-evenly',
];
const alignOptions = ['flex-start', 'center', 'flex-end'];
const justify = ref<FlexJustify>('flex-start');
const align = ref<FlexAlign>('flex-start');
const boxStyle = {
  width: '100%',
  height: '120px',
  borderRadius: 'var(--apollo-border-radius)',
  border: '1px solid var(--apollo-color-border)',
};
</script>

<template>
  <Flex gap="medium" align="start" vertical>
    <p>Select justify :</p>
    <Select v-model:value="justify" aria-label="Select justify" style="width: 180px" :options="justifyOptions.map(value => ({ value, label: value }))" />
    <p>Select align :</p>
    <Select v-model:value="align" aria-label="Select align" style="width: 180px" :options="alignOptions.map(value => ({ value, label: value }))" />
    <Flex :style="boxStyle" :justify="justify" :align="align">
      <Button>Task</Button>
      <Button>Task</Button>
      <Button>Task</Button>
      <Button>Task</Button>
    </Flex>
  </Flex>
</template>
```

## 设置间隙 (gap)

三档预设消费当前主题别名；自定义滑块支持零间距，并在条件出现时保留独立名称。

### gap.vue

```vue
<script setup lang="ts">
import type { FlexProps } from '@apollo-design/ui';
import { Button, Flex, Radio, Slider } from '@apollo-design/ui';
import { ref } from 'vue';

const gapSize = ref<FlexProps['gap']>('small');
const customGapSize = ref(0);
</script>

<template>
  <Flex gap="middle" vertical>
    <fieldset style="margin: 0; padding: 0; border: 0; min-width: 0">
      <legend>Gap preset</legend>
      <Radio.Group v-model:value="gapSize" :options="['small', 'medium', 'large', 'customize']" />
    </fieldset>
    <template v-if="gapSize === 'customize'">
      <span>Custom gap</span>
      <Slider v-model:value="customGapSize" aria-label="Custom gap" :min="0" :max="64" style="width: 100%" />
      <output>{{ customGapSize }}px</output>
    </template>
    <Flex :gap="gapSize !== 'customize' ? gapSize : customGapSize" wrap>
      <Button>First</Button>
      <Button>Second</Button>
      <Button>Third</Button>
      <Button>Fourth</Button>
    </Flex>
  </Flex>
</template>
```

## 自动换行 (wrap)

真实按钮按可用宽度自动换行，保留原生 Tab 顺序。

### wrap.vue

```vue
<script setup lang="ts">
import { Button, Flex } from '@apollo-design/ui';
</script>

<template>
  <Flex wrap gap="small">
    <Button v-for="i in 24" :key="i">Button</Button>
  </Flex>
</template>
```

## 组合使用 (combination)

嵌套 Flex 构建响应式项目摘要；本地内容无需外部图片，详情按钮展开业务说明。

### combination.vue

```vue
<script setup lang="ts">
import { Button, Flex } from '@apollo-design/ui';
import { ref } from 'vue';

const expanded = ref(false);
</script>

<template>
  <Flex wrap gap="middle" align="stretch" style="max-width: 620px; width: 100%; border: 1px solid var(--apollo-color-border); border-radius: var(--apollo-border-radius); overflow: hidden; box-sizing: border-box">
    <Flex vertical justify="center" flex="1 1 180px" style="min-width: 0; padding: 24px; box-sizing: border-box; background: var(--apollo-color-fill-alter)">
      <strong>Project Apollo</strong>
      <span>Shared workspace</span>
    </Flex>
    <Flex vertical align="flex-start" justify="space-between" gap="small" flex="1 1 240px" style="min-width: 0; padding: 24px; box-sizing: border-box">
      <h3 style="margin: 0">Keep the team in sync</h3>
      <p style="margin: 0">Use nested Flex layouts for a responsive project summary.</p>
      <Button :aria-expanded="expanded" @click="expanded = !expanded">{{ expanded ? 'Hide details' : 'Show details' }}</Button>
      <p v-if="expanded" style="margin: 0">Three milestones are ready for review.</p>
    </Flex>
  </Flex>
</template>
```

## 布局块 (debug)

观察纵向和横向不同高度的装饰块；不为每个子项增加包裹元素。

### debug.vue

```vue
<script setup lang="ts">
import { Flex } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical>
    <div v-for="i in 4" :key="i" :style="{ height: '60px', backgroundColor: i % 2 ? 'var(--apollo-color-primary)' : 'var(--apollo-color-primary-bg-hover)' }" />
  </Flex>
  <Flex style="margin-top: 20px">
    <div
      v-for="i in 4"
      :key="i"
      :style="{ width: '25%', height: i % 2 ? '60px' : '40px', backgroundColor: i % 2 ? 'var(--apollo-color-primary)' : 'var(--apollo-color-primary-bg-hover)' }"
    />
  </Flex>
</template>
```

---

# FloatButton

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/float-button


固定在页面边缘的操作按钮，可组合为操作列表或回到顶部按钮。

## 何时使用

- 提供回到顶部、客服、反馈等全局操作。
- 使用 `FloatButtonGroup` 收纳一组相关操作。

## 代码演示

全部 14 个示例见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/float-button/demo)。

## API

### FloatButton

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 按钮类型 | `'default' \| 'primary'` | `'default'` |
| shape | 按钮形状；Group 内跟随组形状 | `'circle' \| 'square'` | `'circle'` |
| disabled | 禁用，未指定时继承 ConfigProvider | `boolean` | `false` |
| href / target | 链接地址与打开目标，指定 href 时渲染为 a | `string` | — |
| htmlType | 原生 button 类型 | `'button' \| 'submit' \| 'reset'` | `'button'` |
| aria-label | 按钮的可访问名称 | `string` | — |
| tooltip | Tooltip 内容或配置对象 | `string \| TooltipProps` | — |
| badge | Badge 配置，不含 status、text、title、children | `FloatButtonBadgeProps` | — |
| description | 已废弃，使用 `#content` | `string` | — |
| prefixCls | 完整类名前缀 | `string` | `'apollo-float-btn'` |
| classNames / styles | root、icon、content 语义区域，支持 `({ props }) => ...` | `FloatButtonProps['classNames' / 'styles']` | — |

`#icon` 自定义完整图标内容；没有图标槽且内容为空时使用默认图标。`#content` 提供完整内容，文字建议搭配 `shape="square"`。插槽存在即优先，包含有意返回空内容的情况；动态增删、文本、数组和 Fragment 均随当前渲染更新。FloatButton 没有默认插槽和 v-model。

`@click` 只发出一次真实 `MouseEvent`。禁用状态遵循原生 Button 的交互规则。

根 `class`、`style`、id、ARIA 和原生监听器落在真实 button/a 上；style 支持 Vue 字符串、对象和数组。样式优先级为当前主题、Provider 根 style、语义 root style、原生 style；显式 zIndex（包括 0）保留。

### FloatButtonGroup

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| trigger | click/hover 菜单；省略时始终显示列表 | `'click' \| 'hover'` | — |
| open | 受控开合，支持 `v-model:open` | `boolean` | 非受控初始关闭 |
| placement | 列表展开方向 | `'top' \| 'left' \| 'right' \| 'bottom'` | `'top'` |
| shape | 列表和触发按钮的形状；circle 使用 Flex，square 使用 Space.Compact | `'circle' \| 'square'` | `'circle'` |
| type / disabled / href / target / htmlType / tooltip / badge / aria-label | 触发按钮配置；子按钮各自声明对应属性 | 同 FloatButton | — |
| prefixCls | 完整类名前缀 | `string` | `'apollo-float-btn'` |
| classNames / styles | root、list、item、itemIcon、itemContent、trigger、triggerIcon、triggerContent | 对象或 `({ props }) => 对象` | — |

| 事件 | 载荷 | 说明 |
|---|---|---|
| update:open | `boolean` | 开合提议，供 `v-model:open` 使用 |
| openChange | `boolean` | 与 update:open 同源、同次发出 |
| click | `MouseEvent` | 触发按钮的真实点击 |

`#default` 提供列表；`#icon`、`#closeIcon`、`#content` 分别提供触发按钮的关闭时图标、展开时图标和文字内容。触发按钮与列表按钮分别消费 trigger 和 item 语义区域。

Group 的原生 attrs 只落在外层 div，触发按钮属性使用上表字段和 trigger 语义区域。受控状态仅在父级接受后改变；撤销受控保留最后接受值。click 支持外部点击关闭；hover 同时支持焦点进入和原生按钮激活。Escape 请求关闭，焦点位于列表内且关闭已接受时返回触发按钮；关闭被拒绝或焦点已移到外部时保留当前焦点。

### FloatButtonBackTop

继承 FloatButton 的属性、`#icon` / `#content` 和 `@click`，其中 target 改为滚动容器 getter。

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| visibilityHeight | 滚动到该高度时可见 | `number` | `400` |
| duration | 回顶动画时长，毫秒；小于等于 0 立即回顶 | `number` | `450` |
| showProgress | 显示滚动进度环 | `boolean` | `false` |
| target | 当前滚动容器，待绑定的 ref 可返回 null | `() => HTMLElement \| Window \| Document \| null` | 按钮所属 document |

目标、阈值、进度开关响应动态变化。重复点击、目标切换和卸载取消当前滚动动画；减少动态效果偏好和主题 `motion: false` 使用即时回顶。滚动和 resize 监听随目标及所属 window 释放。

### Provider 与主题

`ConfigProvider.components.floatButton` 和 `floatButtonGroup` 分别提供 `className`、`style`、`classNames`、`styles`。配置替换、移除、嵌套作用域以及 prefixCls/direction 跟随当前值。FloatButton 没有组件 Token；尺寸、边距、颜色、阴影和动画读取当前全局 Alias Token。

### Expose

FloatButton 和 FloatButtonBackTop 公开只读 `nativeElement: HTMLButtonElement | HTMLAnchorElement | null`；Group 为 `HTMLDivElement | null`。隐藏或卸载的 BackTop 可以为 null。没有额外的命令式方法。


## 基本 (basic)

最简单的用法（默认 FileTextOutlined 图标）。`position: fixed` 以独立视口为参照，因此该示例在视口画布中展示。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic.tsx
import { FloatButton } from '@apollo-design/ui';

const onClick = () => console.log('onClick');
</script>

<template>
  <FloatButton @click="onClick" />
</template>
```

## 组件组 (group)

`FloatButtonGroup`（circle ⇒ Flex 独立排列；square ⇒ Space.Compact 紧凑）。同样以独立视口为定位参照。

### group.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/group.tsx
import { QuestionCircleOutlined, SyncOutlined } from '@apollo-design/icons';
import { FloatButton, FloatButtonBackTop, FloatButtonGroup } from '@apollo-design/ui';
</script>

<template>
  <div>
    <FloatButtonGroup shape="circle" style="inset-inline-end: 24px">
      <FloatButton #icon><QuestionCircleOutlined /></FloatButton>
      <FloatButton />
      <FloatButtonBackTop :visibility-height="0" />
    </FloatButtonGroup>
    <FloatButtonGroup shape="square" style="inset-inline-end: 94px">
      <FloatButton #icon><QuestionCircleOutlined /></FloatButton>
      <FloatButton />
      <FloatButton #icon><SyncOutlined /></FloatButton>
      <FloatButtonBackTop :visibility-height="0" />
    </FloatButtonGroup>
  </div>
</template>
```

## 回到顶部 (back-top)

`FloatButton.BackTop` 通过 `target` 指定滚动容器，`visibilityHeight` 控制出现阈值，`showProgress` 展示进度环。

### back-top.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `back-top` demo：指定滚动容器并展示进度环。
import { FloatButtonBackTop, Text } from '@apollo-design/ui';
import { ref } from 'vue';

const scrollContainer = ref<HTMLElement | null>(null);
const scrollTop = ref(0);

const getTarget = () => scrollContainer.value;

const onScroll = (event: Event) => {
  scrollTop.value = Math.round((event.currentTarget as HTMLElement).scrollTop);
};
</script>

<template>
  <div>
    <Text type="secondary">在下方容器内滚动，超过 80px 后显示带进度环的回到顶部按钮。</Text>
    <div
      ref="scrollContainer"
      style="height: 240px; overflow-y: auto; margin-top: 12px; padding: 12px; border: 1px solid var(--apollo-color-border); border-radius: 8px"
      tabindex="0"
      aria-label="FloatButton scroll content"
      @scroll="onScroll"
    >
      <div v-for="i in 40" :key="i" style="padding: 6px 0">Scroll content {{ i }}</div>
    </div>
    <div style="margin-top: 8px"><Text type="secondary">scrollTop: {{ scrollTop }}px</Text></div>
    <FloatButtonBackTop
      :target="getTarget"
      :visibility-height="80"
      :duration="300"
      show-progress
    />
  </div>
</template>
```

## 悬浮按钮组方位 (group-placement)

用 `Segmented` 切换 `FloatButtonGroup` 的 `placement`（top / right / bottom / left），点击触发按钮展开菜单。

### group-placement.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `placement` demo：用 Segmented 切换 FloatButtonGroup 的四个方位。
import { CommentOutlined, CustomerServiceOutlined } from '@apollo-design/icons';
import type { FloatButtonGroupPlacement, SegmentedValue } from '@apollo-design/ui';
import { FloatButton, FloatButtonGroup, Segmented } from '@apollo-design/ui';
import { ref } from 'vue';

const placement = ref<FloatButtonGroupPlacement>('right');

const options: { label: string; value: FloatButtonGroupPlacement }[] = [
  { label: 'Top', value: 'top' },
  { label: 'Right', value: 'right' },
  { label: 'Bottom', value: 'bottom' },
  { label: 'Left', value: 'left' },
];

const onPlacementChange = (value: SegmentedValue) => {
  placement.value = value as FloatButtonGroupPlacement;
};
</script>

<template>
  <div>
    <Segmented :value="placement" :options="options" @change="onPlacementChange" />
    <FloatButtonGroup
      :key="placement"
      :placement="placement"
      trigger="click"
      type="primary"
      style="inset: 50% auto auto 50%; transform: translate(-50%, -50%)"
    >
      <template #icon><CustomerServiceOutlined /></template>
      <FloatButton #icon><CommentOutlined /></FloatButton>
      <FloatButton tooltip="Settings" />
    </FloatButtonGroup>
  </div>
</template>
```

## badge (badge)

`badge` 数据 prop（dot / count / color）。

### badge.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/badge.tsx（badge 数据 prop）
import { QuestionCircleOutlined } from '@apollo-design/icons';
import { FloatButton, FloatButtonBackTop, FloatButtonGroup } from '@apollo-design/ui';
</script>

<template>
  <div>
    <FloatButton shape="circle" style="inset-inline-end: 164px" :badge="{ dot: true }" />
    <FloatButtonGroup shape="circle" style="inset-inline-end: 94px">
      <FloatButton :badge="{ count: 5, color: 'blue' }" />
      <FloatButton :badge="{ count: 5 }" />
    </FloatButtonGroup>
    <FloatButtonGroup shape="circle">
      <FloatButton :badge="{ count: 12 }" #icon>
        <QuestionCircleOutlined />
      </FloatButton>
      <FloatButton :badge="{ count: 123, overflowCount: 999 }" />
      <FloatButtonBackTop :visibility-height="0" />
    </FloatButtonGroup>
  </div>
</template>
```

## content (content)

`#content` 插槽（deprecated `description` 的对应物）。

### content.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/content.tsx（C8-R2：content → #content 插槽）
import { FileTextOutlined } from '@apollo-design/icons';
import { FloatButton } from '@apollo-design/ui';
</script>

<template>
  <div>
    <FloatButton shape="square" style="inset-inline-end: 164px">
      <template #content>HELP</template>
      <template #icon><FileTextOutlined /></template>
    </FloatButton>
    <FloatButton shape="square" style="inset-inline-end: 94px">
      <template #content>HELP INFO</template>
      <template #icon><FileTextOutlined /></template>
    </FloatButton>
    <FloatButton shape="square" style="inset-inline-end: 24px">
      <template #content>HELP INFO</template>
    </FloatButton>
  </div>
</template>
```

## controlled (controlled)

受控 `open`（`v-model:open`，需与 `trigger` 同用）。

### controlled.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/controlled.tsx（受控 open）
import { CustomerServiceOutlined } from '@apollo-design/icons';
import { FloatButton, FloatButtonGroup } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const changes = ref(0);
</script>

<template>
  <div aria-live="polite">{{ open ? 'Expanded' : 'Closed' }} · changes: {{ changes }}</div>
  <FloatButtonGroup
    v-model:open="open"
    trigger="click"
    type="primary"
    style="inset-inline-end: 24px"
    aria-label="Support actions"
    @open-change="changes++"
  >
    <template #icon><CustomerServiceOutlined /></template>
    <FloatButton />
  </FloatButtonGroup>
</template>
```

## group-menu (group-menu)

menu 模式：`trigger="click" | "hover"` 弹出菜单。

### group-menu.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/group-menu.tsx
import { CommentOutlined, CustomerServiceOutlined } from '@apollo-design/icons';
import { FloatButton, FloatButtonGroup } from '@apollo-design/ui';
</script>

<template>
  <div>
    <FloatButtonGroup trigger="click" type="primary" style="inset-inline-end: 24px">
      <template #icon><CustomerServiceOutlined /></template>
      <FloatButton />
      <FloatButton #icon><CommentOutlined /></FloatButton>
    </FloatButtonGroup>
    <FloatButtonGroup trigger="hover" type="primary" style="inset-inline-end: 94px">
      <template #icon><CustomerServiceOutlined /></template>
      <FloatButton />
      <FloatButton #icon><CommentOutlined /></FloatButton>
    </FloatButtonGroup>
  </div>
</template>
```

## placement (placement)

`placement` 菜单弹出方向（top/left/right/bottom）。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/placement.tsx
import { CommentOutlined } from '@apollo-design/icons';
import { FloatButton, FloatButtonGroup } from '@apollo-design/ui';
</script>

<template>
  <FloatButtonGroup trigger="click" placement="top" style="inset-inline-end: 24px">
    <template #icon><CommentOutlined /></template>
    <FloatButton />
  </FloatButtonGroup>
</template>
```

## progress-ring (progress-ring)

`showProgress` 进度环（conic-gradient，`--{prefix}-float-btn-progress` 变量）。

### progress-ring.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/progress-ring.tsx（showProgress 进度环）
import { FloatButtonBackTop } from '@apollo-design/ui';
</script>

<template>
  <div style="height: 300vh; padding: 10px">
    <div>Scroll to bottom</div>
    <FloatButtonBackTop :visibility-height="0" show-progress />
  </div>
</template>
```

## shape (shape)

`shape="circle" | "square"` 两种形状。

### shape.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/shape.tsx
import { CustomerServiceOutlined } from '@apollo-design/icons';
import { FloatButton } from '@apollo-design/ui';
</script>

<template>
  <div>
    <FloatButton #icon shape="circle" type="primary" style="inset-inline-end: 94px">
      <CustomerServiceOutlined />
    </FloatButton>
    <FloatButton #icon shape="square" type="primary" style="inset-inline-end: 24px">
      <CustomerServiceOutlined />
    </FloatButton>
  </div>
</template>
```

## style-class (style-class)

语义化 `classNames` / `styles`。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx
import { FloatButton } from '@apollo-design/ui';
</script>

<template>
  <FloatButton
    :class-names="{ root: 'demo-fb-root', icon: 'demo-fb-icon' }"
    :styles="{ icon: { color: 'blue' } }"
  />
</template>
```

## tooltip (tooltip)

`tooltip` 数据 prop（string 或 TooltipProps 对象）。

### tooltip.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/tooltip.tsx（tooltip 数据 prop；string / TooltipProps 对象）
import { FloatButton } from '@apollo-design/ui';
</script>

<template>
  <div>
    <FloatButton
      style="inset-block-end: 108px"
      :tooltip="{ title: 'Since 5.25.0+', color: 'blue', placement: 'top' }"
    />
    <FloatButton tooltip="Documents" />
  </div>
</template>
```

## type (type)

`type="primary" | "default"` 两种类型（`#icon` 插槽自定义图标）。

### type.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/type.tsx
import { QuestionCircleOutlined } from '@apollo-design/icons';
import { FloatButton } from '@apollo-design/ui';
</script>

<template>
  <div>
    <FloatButton #icon type="primary" style="inset-inline-end: 24px">
      <QuestionCircleOutlined />
    </FloatButton>
    <FloatButton #icon type="default" style="inset-inline-end: 94px">
      <QuestionCircleOutlined />
    </FloatButton>
  </div>
</template>
```

---

# Form

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/form


# Form 表单

具有数据收集、校验和提交功能的表单，包含复选框、单选框、输入框、下拉选择框等元素。

## 何时使用

- 需要创建一个原生表单，可能包含各种交互式控件；
- 提交前需要校验用户输入（同步/异步规则）；
- 需要动态增删表单项（`Form.List`）。

## 引入

```ts
import { Form, FormItem, FormList, useForm, useWatch, ErrorList } from '@apollo-design/ui';
// 或复合写法
import { Form } from '@apollo-design/ui';
const { Item, List, useForm, useWatch, ErrorList } = Form;
```

## 代码演示











## API

### FormProps

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| form | 表单实例（`useForm()` 创建） | FormInstance | - |
| name | 表单名（fieldId 前缀 + FormProvider 注册键） | string | - |
| layout | 布局 | 'horizontal' \| 'vertical' \| 'inline' | 'horizontal' |
| labelCol / wrapperCol | label / 控件列宽（grid ColProps） | ColProps | - |
| labelAlign | label 对齐 | 'left' \| 'right' | 'right' |
| labelWrap | label 换行 | boolean | - |
| colon | 冒号（vertical 布局无效） | boolean | - |
| requiredMark | 必填标记；自定义内容使用 requiredMark 插槽 | boolean \| 'optional' | true |
| initialValues | 初值 | object | - |
| validateMessages | 校验文案模板 | ValidateMessages | - |
| validateTrigger | 触发校验的事件 | string \| string[] \| false | 'onChange' |
| preserve | 字段卸载后保留值 | boolean | true |
| clearOnDestroy | 表单卸载时清除值 | boolean | false |
| fields | 受控字段值及状态；数组替换和字段内更新都会同步 | FieldData[] | - |
| disabled | 整表禁用 | boolean | - |
| size / variant / tooltip | 表单态与标签提示配置 | - | - |
| scrollToFirstError | 校验失败滚动到首个错误字段 | boolean \| ScrollOptions | - |
| component | 容器元素（false 不渲染） | string \| Component \| false | 'form' |
| renderProps | 让默认槽的 values 随 store 更新；字段仍处理自身状态与重置 | boolean | false |
| classNames / styles | 语义槽（root/label/content/help/helpItem/extra）。⚠️ 也接受**函数形态**（`(info) => …`）；根槽与 `ConfigProvider components.form` 及调用方原生 `class` / `style` **合并**（原生 `style` 胜） | object \| function | - |

### 事件（Emits）

`finish(values)` / `finishFailed(errorInfo)` / `valuesChange(changed, all)` / `fieldsChange(changed, all)`；`update:*` 不适用（值由 store 管理）。

默认作用域插槽为 `{ values, form }`。例如 `<Form render-props v-slot="{ values }">…</Form>`；普通字段表单可省略 `render-props`，字段继续独立订阅。

内容槽：`requiredMark({ label, required })` 与 `feedbackIcon({ status, errors, warnings })`。`label` 是保留原始标签内容的稳定组件，模板中使用 `<component :is="label" />`。Form.Item 的同名 feedbackIcon 槽优先于 Form 槽；槽撤除后立即恢复当前默认内容。

### FormInstance（expose）

`getFieldValue` / `getFieldsValue` / `setFieldValue` / `setFieldsValue` / `resetFields` / `validateFields` / `submit` / `getFieldsError` / `getFieldError` / `getFieldWarning` / `isFieldsTouched` / `isFieldTouched` / `isFieldValidating` / `isFieldsValidating` / `setFields` / `getFieldInstance(name)` / `scrollToField(name, options)` / `focusField(name)` / `nativeElement`。

`getFieldInstance` 返回已挂载控件的真实 DOM 或 Vue 公开引用对象（`object | undefined`），保持调用方模板 ref 的身份；不能假定每个自定义 expose 都有 focus 方法。`focusField` 在实际支持的能力上聚焦，`scrollToField` 使用真实控件元素，`{ focus: true }` 可同时聚焦。`nativeElement` 是实际 HTML 容器，无容器时为 null。

### Form.Item

props：`name`（NamePath）、`rules`、`dependencies`、`trigger`、`valuePropName`、`getValueFromEvent`、`getValueProps`、`normalize`、`validateTrigger`、`validateFirst`、`preserve`、`initialValue`、`messageVariables`、`shouldUpdate`；展示：`label` / `labelCol` / `wrapperCol` / `colon` / `required` / `tooltip` / `noStyle` / `help` / `extra` / `hasFeedback`（boolean）/ `validateStatus` / `hidden` / `htmlFor` / `layout`。

slots：`default({ control, meta, form })`（子控件；有 name 时单个控件被注入 value 与事件）、`label` / `help` / `extra` / `tooltip` / `feedbackIcon({ status, errors, warnings })`。内容槽优先于对应 prop，显式空槽不会回退到 prop。无字段的布局项也提供同一对象，control 为空、meta 为当前空状态；脱离 Form 的布局项 form 为 undefined。

Form 与有布局壳的 Form.Item 将原生 class/style、属性和监听器落到各自实际根元素。noStyle 项与 Form.List 没有 DOM 根。labelCol/wrapperCol 使用 Grid ColProps 并可携带原生 class/style，嵌套布局项不会继承外层列宽。

事件：`reset()` / `metaChange(meta)`，分别使用 `@reset` / `@meta-change`。组件不手动调用同名回调 Prop。

动态 `prefixCls` 与布局变更会更新派生类、真实控件的反馈图标、错误/帮助内容，并按已加载 CSS 重新测量 margin 占位。`Form.ErrorList` 独立使用时读取 ConfigProvider 前缀；在 Form.Item / Form.List 中使用最近的前缀上下文。动态前缀需要预先提供对应的静态 CSS，组件不会生成运行时样式。

### Form.List

props：`name`。scoped slot `{ fields, operations, meta }` —— `fields: { name, key, fieldKey }[]`、`operations: { add, remove, move }`、`meta: { errors, warnings }`。`Form.ErrorList` 用于展示 List 级错误。

`Form.ErrorList` 接受 help/errors/warnings 与原生根属性，`visibleChanged(visible: boolean)` 是所属事件。重复消息保留独立行，离场行使用最后收到的内容，结束后释放布局占位；不再从已经移除的当前 keys 反查消息。

### useWatch

`useWatch(dependencies, form)` 或 `useWatch(dependencies, { form, preserve })` —— 返回监听字段路径/selector 的 Ref，随调用它的 effect scope 释放。

`useFormInstance()` 读取最近 Form 的现有实例；Form 外返回 undefined，不创建新 store。重复 `useForm(form)` 与直接传给 Form 的同一外建实例共用控件注册表。

开发版直接把 Form / Form.Item 的旧位置参数槽迁为具名对象；requiredMark 内容函数、feedbackIcons 与 hasFeedback.icons 改用上述内容槽，不提供兼容层或弃用期。Form.List 既有对象作用域保持不变。校验器、取值/归一算法与异步业务回调仍是函数。

### 主题变量

11 个（`labelRequiredMarkColor` / `labelColor` / `labelFontSize` / `labelHeight` / `verticalLabelHeight` / `labelColonMarginInlineStart` / `labelColonMarginInlineEnd` / `itemMarginBottom` / `verticalLabelPadding` / `verticalLabelMargin` / `inlineItemMarginBottom`）。

使用 `ConfigProvider theme.components.Form` 配置，支持当前主题/组件 Token 替换与撤除，并作用于独立 Form.Item。长度数值会转换为 px；`verticalLabelHeight` 也接受 `'auto'`。原生 style 中的 `--apollo-form-*` 变量保留局部覆盖优先级，自定义前缀使用对应的变量前缀。


## 动态表单 (form-list)

`Form.List` 的默认插槽给出 `{ fields, operations, meta }`：`fields` 用于 `v-for` 渲染，`operations.add/remove/move` 操作行。示例支持增删用户，提交后由 `message` 给出反馈。

### form-list.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/form-list.tsx：动态增删字段
import { MinusCircleOutlined, PlusOutlined } from '@apollo-design/icons';
import { Button, Flex, Form, FormItem, FormList, Input, message, useForm } from '@apollo-design/ui';

const [form] = useForm();
// Form.List 的行由表单 store 初始化（不是模板里的 model 对象）。
const initialValues = {
  users: [{ first: 'Jane', last: 'Doe' }],
};

const onFinish = (values: unknown) => {
  message.success('提交成功');
  console.log('Received values of form:', values);
};
</script>

<template>
  <Form :form="form" :initial-values="initialValues" layout="vertical" @finish="onFinish">
    <FormList name="users">
      <template #default="{ fields, operations }">
        <Flex
          v-for="field in fields"
          :key="field.key"
          align="flex-start"
          gap="small"
          class="demo-list-row"
        >
          <FormItem
            :name="[field.name, 'first']"
            label="First Name"
            :rules="[{ required: true, message: '请输入名' }]"
            style="flex: 1"
          >
            <Input placeholder="first name" />
          </FormItem>
          <FormItem
            :name="[field.name, 'last']"
            label="Last Name"
            :rules="[{ required: true, message: '请输入姓' }]"
            style="flex: 1"
          >
            <Input placeholder="last name" />
          </FormItem>
          <Button
            type="text"
            danger
            :icon="MinusCircleOutlined"
            aria-label="删除该行"
            style="margin-top: 30px"
            @click="operations.remove(field.name)"
          />
        </Flex>
        <FormItem>
          <Button type="dashed" block :icon="PlusOutlined" @click="operations.add()">
            Add field
          </Button>
        </FormItem>
      </template>
    </FormList>
    <FormItem>
      <Button type="primary" html-type="submit">Submit</Button>
    </FormItem>
  </Form>
</template>
```

## 嵌套动态表单 (form-list-nested)

`Form.List` 可以嵌套：内层 `name` 用 `[field.name, 'tags']` 定位到父行，字段名路径会按层级展开。示例支持每个用户维护一组标签。

### form-list-nested.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/form-list-nested.tsx：嵌套 namePath
import { MinusCircleOutlined, PlusOutlined } from '@apollo-design/icons';
import { Button, Flex, Form, FormItem, FormList, Input, useForm } from '@apollo-design/ui';

const [form] = useForm();
const initialValues = {
  users: [
    { name: 'Alice', tags: ['frontend'] },
    { name: 'Bob', tags: [] as string[] },
  ],
};
</script>

<template>
  <Form :form="form" :initial-values="initialValues" layout="vertical">
    <FormList name="users">
      <template #default="{ fields, operations }">
        <div v-for="field in fields" :key="field.key" class="demo-nested-card">
          <Flex align="flex-start" gap="small">
            <FormItem
              :name="[field.name, 'name']"
              label="用户名"
              :rules="[{ required: true, message: '请输入用户名' }]"
              style="flex: 1"
            >
              <Input placeholder="user name" />
            </FormItem>
            <Button
              type="text"
              danger
              :icon="MinusCircleOutlined"
              aria-label="删除用户"
              style="margin-top: 30px"
              @click="operations.remove(field.name)"
            />
          </Flex>

          <FormList :name="[field.name, 'tags']">
            <template #default="tagSlot">
              <Flex
                v-for="tagField in tagSlot.fields"
                :key="tagField.key"
                align="flex-start"
                gap="small"
              >
                <FormItem
                  :name="tagField.name"
                  label="标签"
                  :rules="[{ required: true, message: '请输入标签' }]"
                  style="flex: 1"
                >
                  <Input placeholder="tag" />
                </FormItem>
                <Button
                  type="text"
                  danger
                  :icon="MinusCircleOutlined"
                  aria-label="删除标签"
                  style="margin-top: 30px"
                  @click="tagSlot.operations.remove(tagField.name)"
                />
              </Flex>
              <FormItem>
                <Button
                  size="small"
                  type="dashed"
                  :icon="PlusOutlined"
                  @click="tagSlot.operations.add()"
                >
                  Add tag
                </Button>
              </FormItem>
            </template>
          </FormList>
        </div>
        <Button type="dashed" block :icon="PlusOutlined" @click="operations.add()">
          Add user
        </Button>
      </template>
    </FormList>
  </Form>
</template>
```

## 监听字段 (use-watch)

`Form.useWatch(name, form)` 返回响应式 `Ref`；示例在两个输入框下方实时显示字段值，无需额外的 `@change` 处理。

### use-watch.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/useWatch.tsx：实时监听字段值
import { Form, FormItem, Input, useForm, useWatch } from '@apollo-design/ui';
import { reactive } from 'vue';

const [form] = useForm();
const formState = reactive({ username: '', age: '' });

const username = useWatch('username', form);
const age = useWatch('age', form);
</script>

<template>
  <Form :form="form" :model="formState" layout="vertical">
    <FormItem label="Username" name="username">
      <Input v-model:value="formState.username" placeholder="请输入用户名" />
    </FormItem>
    <FormItem label="Age" name="age">
      <Input v-model:value="formState.age" placeholder="请输入年龄" />
    </FormItem>
    <div class="demo-watch-panel">
      <div>useWatch('username') = {{ username ?? '（空）' }}</div>
      <div>useWatch('age') = {{ age ?? '（空）' }}</div>
    </div>
  </Form>
</template>
```

## 字段联动 (dependencies)

确认密码的 `FormItem` 声明 `dependencies: ['password']`：密码变化时会重新校验确认框；`validator` 从表单实例读取当前密码并返回 Promise。

### dependencies.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/dependencies.tsx：字段联动校验
import { Form, FormItem, type FormItemProps, Input, useForm } from '@apollo-design/ui';
import { reactive } from 'vue';

const [form] = useForm();
const formState = reactive({ password: '', confirm: '' });

const confirmRules: FormItemProps['rules'] = [
  { required: true, message: '请再次输入密码' },
  {
    validator: (_rule, value) =>
      value === form.getFieldValue('password')
        ? Promise.resolve()
        : Promise.reject(new Error('两次输入的密码不一致')),
  },
];
</script>

<template>
  <Form :form="form" :model="formState" layout="vertical">
    <FormItem
      label="Password"
      name="password"
      :rules="[{ required: true, message: '请输入密码' }]"
    >
      <Input v-model:value="formState.password" type="password" placeholder="Password" />
    </FormItem>
    <FormItem
      label="Confirm"
      name="confirm"
      :dependencies="['password']"
      :rules="confirmRules"
    >
      <Input v-model:value="formState.confirm" type="password" placeholder="Confirm password" />
    </FormItem>
  </Form>
</template>
```

## 异步校验 (async-validation)

`validator` 返回 Promise 时表单进入 validating 状态，`has-feedback` 显示加载图标；示例输入 `admin` 会在 600ms 后被拒绝。

### async-validation.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/validate-only.tsx + 异步校验
import { Form, FormItem, type FormItemProps, Input } from '@apollo-design/ui';

const rules: FormItemProps['rules'] = [
  { required: true, message: '请输入用户名' },
  {
    validator: (_rule, value) =>
      new Promise<void>((resolve, reject) => {
        window.setTimeout(() => {
          if (value === 'admin') {
            reject(new Error('用户名 admin 已被占用'));
          } else {
            resolve();
          }
        }, 600);
      }),
  },
];
</script>

<template>
  <Form layout="vertical">
    <FormItem label="Username" name="username" :rules="rules" has-feedback>
      <Input placeholder="输入 admin 触发异步失败" />
    </FormItem>
  </Form>
</template>
```

## 初始值与重置 (initial-values)

`initialValues` 提供非受控初始值；`form.setFieldsValue` 可以整体回填，`form.resetFields` 恢复到初始值。

### initial-values.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/initial-values.tsx + resetFields
import { Button, Form, FormItem, Input, Space, useForm } from '@apollo-design/ui';

const [form] = useForm();

const initialValues = { username: 'Apollo', email: 'hello@example.com' };

const fill = () => {
  form.setFieldsValue({ username: 'Filled', email: 'filled@example.com' });
};

const reset = () => {
  form.resetFields();
};
</script>

<template>
  <Form :form="form" :initial-values="initialValues" layout="vertical">
    <FormItem label="Username" name="username">
      <Input placeholder="Username" />
    </FormItem>
    <FormItem label="Email" name="email" :rules="[{ type: 'email', message: '邮箱格式不正确' }]">
      <Input placeholder="Email" />
    </FormItem>
    <FormItem>
      <Space wrap>
        <Button type="primary" html-type="submit">Submit</Button>
        <Button @click="fill">setFieldsValue</Button>
        <Button @click="reset">resetFields</Button>
      </Space>
    </FormItem>
  </Form>
</template>
```

## 提交失败 (finish-failed)

`@finishFailed` 拿到 `errorFields`；`scrollToFirstError` 会自动滚动并聚焦到第一条错误。提交成功与失败都在下方给出可见反馈。

### finish-failed.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/finish-failed.tsx
import type { ValidateErrorEntity } from '@apollo-design/form-core';
import { Button, Form, FormItem, Input, useForm } from '@apollo-design/ui';
import { ref } from 'vue';

const [form] = useForm();
const errorInfo = ref('');

const onFinish = (values: unknown) => {
  errorInfo.value = `提交成功：${JSON.stringify(values)}`;
};

const onFinishFailed = (errorInfoValue: ValidateErrorEntity) => {
  errorInfo.value = `校验失败：${errorInfoValue.errorFields
    .map((field) => field.errors.join('、'))
    .join('；')}`;
};
</script>

<template>
  <Form
    :form="form"
    layout="vertical"
    scroll-to-first-error
    @finish="onFinish"
    @finish-failed="onFinishFailed"
  >
    <FormItem
      label="Username"
      name="username"
      :rules="[{ required: true, message: '请输入用户名' }]"
    >
      <Input placeholder="Username" />
    </FormItem>
    <FormItem
      label="Email"
      name="email"
      :rules="[
        { required: true, message: '请输入邮箱' },
        { type: 'email', message: '邮箱格式不正确' },
      ]"
    >
      <Input placeholder="Email" />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">Submit</Button>
    </FormItem>
    <div v-if="errorInfo" class="demo-result">{{ errorInfo }}</div>
  </Form>
</template>
```

## 读写表单值 (set-fields-value)

通过 `useForm()` 实例调用 `getFieldsValue` / `setFieldsValue`，把当前值序列化后展示在页面上；适用于外部按钮触发的批量回填。

### set-fields-value.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/set-fields-value.tsx
import { Button, Form, FormItem, Input, Space, useForm } from '@apollo-design/ui';
import { computed, shallowRef } from 'vue';

const [form] = useForm();
const snapshot = shallowRef('');

const read = () => {
  snapshot.value = JSON.stringify(form.getFieldsValue(true));
};

const write = () => {
  form.setFieldsValue({ username: 'Apollo', email: 'apollo@example.com' });
  read();
};

const output = computed(() => snapshot.value || '（点击按钮读取表单值）');
</script>

<template>
  <Form :form="form" layout="vertical">
    <FormItem label="Username" name="username">
      <Input placeholder="Username" />
    </FormItem>
    <FormItem label="Email" name="email">
      <Input placeholder="Email" />
    </FormItem>
    <FormItem>
      <Space wrap>
        <Button type="primary" @click="read">getFieldsValue</Button>
        <Button @click="write">setFieldsValue</Button>
      </Space>
    </FormItem>
    <div class="demo-result">{{ output }}</div>
  </Form>
</template>
```

## 禁用与尺寸 (disabled-size)

`Form` 的 `disabled` 与 `size` 会级联到所有表单项；示例可实时切换，验证禁用态与三种尺寸。

### disabled-size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/disabled.tsx / size.tsx：Form 级联禁用与尺寸
import { Form, FormItem, Input, Radio, RadioGroup, Switch } from '@apollo-design/ui';
import { ref } from 'vue';

const disabled = ref(true);
const size = ref<'small' | 'middle' | 'large'>('middle');
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; gap: 16px; margin-bottom: 16px; align-items: center">
      <span>disabled</span>
      <Switch v-model:checked="disabled" aria-label="禁用表单" />
      <RadioGroup v-model:value="size" size="small" aria-label="表单尺寸">
        <Radio value="small">small</Radio>
        <Radio value="middle">middle</Radio>
        <Radio value="large">large</Radio>
      </RadioGroup>
    </div>
    <Form :disabled="disabled" :size="size" layout="vertical">
      <FormItem label="Username" name="username">
        <Input placeholder="Username" />
      </FormItem>
      <FormItem label="Email" name="email">
        <Input placeholder="Email" />
      </FormItem>
    </Form>
  </div>
</template>
```

## 滚动到字段 (scroll-to-field)

`form.scrollToField(name, options)` 会把字段滚入最近的滚动容器并聚焦。示例容器限高 240px，点击按钮可直接定位到最后一个字段。

### scroll-to-field.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/scroll-to-field.tsx
import { Button, Form, FormItem, Input, message, useForm } from '@apollo-design/ui';

const [form] = useForm();
const fields = Array.from({ length: 12 }, (_, index) => `field${index}`);

const scrollToLast = () => {
  form.scrollToField?.('field11', { behavior: 'smooth', block: 'center' });
  message.info('已滚动到 field11');
};
</script>

<template>
  <Form :form="form" layout="vertical">
    <div style="max-height: 240px; overflow: auto; padding-inline-end: 8px">
      <FormItem
        v-for="field in fields"
        :key="field"
        :label="field"
        :name="field"
        :rules="[{ required: true, message: `请输入 ${field}` }]"
      >
        <Input :placeholder="field" />
      </FormItem>
    </div>
    <FormItem>
      <Button type="primary" @click="scrollToLast">Scroll to field11</Button>
    </FormItem>
  </Form>
</template>
```

## 高级搜索 (advanced-search)

使用 `Row` / `Col` 栅格把多个 `Form.Item` 排成筛选区，并通过 `v-show` 控制「展开更多筛选」。`Form` 的 `@finish` 会回传所有字段值，`useForm` 返回的 `resetFields()` 用于重置查询条件。所有输入控件都带 `aria-label`，便于辅助技术识别。

### advanced-search.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/advanced-search.tsx：栅格 + 展开/收起的筛选表单。
import { Button, Col, Form, FormItem, Input, Row, Select, useForm } from '@apollo-design/ui';
import { ref } from 'vue';

const [form] = useForm();
const expanded = ref(false);
const submitted = ref('');

const statusOptions = [
  { value: 'running', label: '运行中' },
  { value: 'paused', label: '已暂停' },
  { value: 'finished', label: '已结束' },
];

const ownerOptions = [
  { value: 'apollo', label: 'Apollo' },
  { value: 'workbuddy', label: 'WorkBuddy' },
];

const onFinish = (values: unknown) => {
  submitted.value = JSON.stringify(values);
};

const onReset = () => {
  form.resetFields();
  submitted.value = '';
};
</script>

<template>
  <Form :form="form" layout="vertical" @finish="onFinish">
    <Row :gutter="16">
      <Col :xs="24" :sm="12" :lg="8">
        <FormItem label="项目名称" name="keyword">
          <Input aria-label="项目名称" placeholder="请输入项目名称" allow-clear />
        </FormItem>
      </Col>
      <Col :xs="24" :sm="12" :lg="8">
        <FormItem label="负责人" name="owner">
          <Select
            aria-label="负责人"
            placeholder="请选择负责人"
            :options="ownerOptions"
            allow-clear
          />
        </FormItem>
      </Col>
      <Col :xs="24" :sm="12" :lg="8">
        <FormItem label="状态" name="status">
          <Select
            aria-label="项目状态"
            placeholder="请选择状态"
            :options="statusOptions"
            allow-clear
          />
        </FormItem>
      </Col>
      <Col v-show="expanded" :xs="24" :sm="12" :lg="8">
        <FormItem label="创建人" name="creator">
          <Input aria-label="创建人" placeholder="请输入创建人" allow-clear />
        </FormItem>
      </Col>
      <Col v-show="expanded" :xs="24" :sm="12" :lg="8">
        <FormItem label="备注" name="remark">
          <Input aria-label="备注" placeholder="请输入备注" allow-clear />
        </FormItem>
      </Col>
    </Row>
    <div class="demo-search-actions">
      <Button type="primary" html-type="submit">搜索</Button>
      <Button @click="onReset">重置</Button>
      <Button type="link" @click="expanded = !expanded">
        {{ expanded ? '收起筛选' : '展开更多筛选' }}
      </Button>
    </div>
    <div class="demo-search-result">
      {{ submitted ? `查询条件：${submitted}` : '点击「搜索」查看表单收集到的查询条件。' }}
    </div>
  </Form>
</template>

<style scoped>
.demo-search-actions {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
  align-items: center;
}

.demo-search-result {
  margin-top: 12px;
  padding: 8px 12px;
  color: var(--apollo-color-text-secondary);
  background: var(--apollo-color-fill-alter);
  border-radius: 6px;
  word-break: break-all;
}
</style>
```

## 复杂表单控件 (complex-form-control)

当控件的值与表单存储值不是同一单位时，用 `Form.Item` 的 `getValueProps` 把存储值转换成控件展示值，再用 `getValueFromEvent` 把控件事件转换回存储格式。示例中表单内部以「分」存储金额，`InputNumber` 展示与输入的是「元」；`useWatch('price')` 实时显示底层存储值。

### complex-form-control.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/complex-form-control.tsx：
// `getValueProps` 把表单里存储的「分」转换成输入框展示的「元」，
// `getValueFromEvent` 再把输入框的「元」写回成「分」。
import type { FormItemProps } from '@apollo-design/ui';
import { Form, FormItem, InputNumber, useForm, useWatch } from '@apollo-design/ui';

const [form] = useForm();

const getValueProps: NonNullable<FormItemProps['getValueProps']> = (value) => ({
  value: typeof value === 'number' ? value / 100 : undefined,
});

const getValueFromEvent: NonNullable<FormItemProps['getValueFromEvent']> = (value) =>
  typeof value === 'number' ? Math.round(value * 100) : value;

const priceInCents = useWatch('price', form);
</script>

<template>
  <Form :form="form" :initial-values="{ price: 1999 }" layout="vertical">
    <FormItem
      label="金额（元）"
      name="price"
      :get-value-props="getValueProps"
      :get-value-from-event="getValueFromEvent"
      :rules="[{ required: true, message: '请输入金额' }]"
      extra="输入框展示元，表单内部以「分」存储。"
    >
      <InputNumber
        aria-label="金额（元）"
        placeholder="请输入金额"
        :min="0"
        :step="0.01"
        style="width: 200px"
      />
    </FormItem>
    <div class="demo-cents">
      表单存储值：<strong>{{ priceInCents ?? '（空）' }}</strong> 分
    </div>
  </Form>
</template>

<style scoped>
.demo-cents {
  padding: 8px 12px;
  color: var(--apollo-color-text-secondary);
  background: var(--apollo-color-fill-alter);
  border-radius: 6px;
}
</style>
```

## 组件 Token (component-token)

通过 `ConfigProvider theme.components.Form` 设置组件 Token；当前配置会同步作用于 Form 和独立 Form.Item，配置替换或撤除后也会更新。示例共用一份配置展示 vertical 与 inline 布局。需要局部覆盖时仍可在 Form 或 Form.Item 的原生 `style` 中设置 `--apollo-form-*` CSS 变量。

### component-token.vue

```vue
<script setup lang="ts">
import type { ThemeConfig } from '@apollo-design/theme';
import { Button, ConfigProvider, Form, FormItem, Input, Select } from '@apollo-design/ui';

const theme: ThemeConfig = {
  components: {
    Form: {
      labelColor: '#722ed1',
      labelRequiredMarkColor: '#eb2f96',
      labelFontSize: 15,
      itemMarginBottom: 16,
      verticalLabelPadding: '0 0 4px',
      inlineItemMarginBottom: 8,
      labelColonMarginInlineEnd: 4,
    },
  },
};

const genderOptions = [
  { value: 'female', label: '女' },
  { value: 'male', label: '男' },
];
</script>

<template>
  <ConfigProvider :theme="theme">
    <div class="demo-token-list">
      <Form layout="vertical" :initial-values="{ name: 'Apollo' }">
        <FormItem label="用户名" name="name" :rules="[{ required: true, message: '请输入用户名' }]">
          <Input aria-label="用户名" placeholder="请输入用户名" />
        </FormItem>
        <FormItem label="性别" name="gender">
          <Select aria-label="性别" placeholder="请选择性别" :options="genderOptions" />
        </FormItem>
      </Form>

      <Form layout="inline">
        <FormItem label="关键词" name="keyword">
          <Input aria-label="关键词" placeholder="请输入关键词" />
        </FormItem>
        <FormItem>
          <Button type="primary" html-type="submit">查询</Button>
        </FormItem>
      </Form>
    </div>
  </ConfigProvider>
</template>

<style scoped>
.demo-token-list {
  display: flex;
  flex-direction: column;
  gap: 24px;
}
</style>
```

## 表单方法调用 (control-hooks)

通过 `useForm()` 取得表单实例后，可以调用 `setFieldsValue`、`getFieldsValue`、`validateFields`、`validateFields({ validateOnly: true })` 与 `resetFields`。`validateFields` 校验失败时会 reject，示例捕获 `errorFields` 并把结果显示在页面上；`validateOnly` 只执行校验，不返回字段值。

`render-props` 使默认作用域插槽的 `{ values, form }` 随 store 更新；示例直接显示当前 `values`，使用外部 `useForm()` 实例时也会更新。

### control-hooks.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/control-hooks.tsx：通过 useForm 暴露的实例方法操作表单。
import { Button, Form, FormItem, Input, Space, useForm } from '@apollo-design/ui';
import { ref } from 'vue';

const [form] = useForm();
const output = ref('（尚未调用表单方法）');

const readValues = () => {
  output.value = `getFieldsValue：${JSON.stringify(form.getFieldsValue(true))}`;
};

const fillValues = () => {
  form.setFieldsValue({ username: 'Apollo', email: 'apollo@example.com' });
  readValues();
};

const validate = async () => {
  try {
    const values = await form.validateFields();
    output.value = `validateFields 通过：${JSON.stringify(values)}`;
  } catch (error) {
    const errorFields = (error as { errorFields?: unknown }).errorFields ?? error;
    output.value = `validateFields 失败：${JSON.stringify(errorFields)}`;
  }
};

const validateOnly = async () => {
  try {
    await form.validateFields({ validateOnly: true });
    output.value = 'validateOnly 通过：只校验、不抛出字段值。';
  } catch (error) {
    const errorFields = (error as { errorFields?: unknown }).errorFields ?? error;
    output.value = `validateOnly 失败：${JSON.stringify(errorFields)}`;
  }
};

const reset = () => {
  form.resetFields();
  output.value = 'resetFields：已恢复初始值。';
};
</script>

<template>
  <Form :form="form" layout="vertical" render-props v-slot="{ values }">
    <FormItem
      label="用户名"
      name="username"
      :rules="[{ required: true, message: '请输入用户名' }]"
    >
      <Input aria-label="用户名" placeholder="请输入用户名" />
    </FormItem>
    <FormItem
      label="邮箱"
      name="email"
      :rules="[
        { required: true, message: '请输入邮箱' },
        { type: 'email', message: '邮箱格式不正确' },
      ]"
    >
      <Input aria-label="邮箱" placeholder="请输入邮箱" />
    </FormItem>
    <FormItem>
      <Space wrap>
        <Button @click="fillValues">setFieldsValue</Button>
        <Button @click="readValues">getFieldsValue</Button>
        <Button type="primary" @click="validate">validateFields</Button>
        <Button @click="validateOnly">validateOnly</Button>
        <Button danger @click="reset">resetFields</Button>
      </Space>
    </FormItem>
    <pre class="demo-method-output">{{ output }}</pre>
    <output>当前表单值：{{ JSON.stringify(values) }}</output>
  </Form>
</template>

<style scoped>
.demo-method-output {
  min-height: 48px;
  margin: 0;
  padding: 8px 12px;
  overflow: auto;
  color: var(--apollo-color-text-secondary);
  white-space: pre-wrap;
  background: var(--apollo-color-fill-alter);
  border-radius: 6px;
  word-break: break-all;
}
</style>
```

## 动态表单项 (dynamic-form-item)

`useWatch('accountType', form)` 监听账号类型，配合 `v-if` 动态渲染「公司名称」字段。`Form.Item` 的 `rules` 只在该字段实际存在时参与校验；切换类型后，已隐藏字段的值不会阻止表单提交。

### dynamic-form-item.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/dynamic-form-item.tsx：用 useWatch 监听字段值，条件渲染 Form.Item。
import { Button, Form, FormItem, Input, Select, useForm, useWatch } from '@apollo-design/ui';
import { ref } from 'vue';

const [form] = useForm();
const accountType = useWatch('accountType', form);
const submitted = ref('');

const accountOptions = [
  { value: 'personal', label: '个人账号' },
  { value: 'company', label: '企业账号' },
];

const onFinish = (values: unknown) => {
  submitted.value = JSON.stringify(values);
};
</script>

<template>
  <Form
    :form="form"
    :initial-values="{ accountType: 'personal' }"
    layout="vertical"
    @finish="onFinish"
  >
    <FormItem label="账号类型" name="accountType" :rules="[{ required: true }]">
      <Select aria-label="账号类型" :options="accountOptions" />
    </FormItem>
    <FormItem
      label="用户名"
      name="username"
      :rules="[{ required: true, message: '请输入用户名' }]"
    >
      <Input aria-label="用户名" placeholder="请输入用户名" />
    </FormItem>
    <FormItem
      v-if="accountType === 'company'"
      label="公司名称"
      name="companyName"
      :rules="[{ required: true, message: '企业账号必须填写公司名称' }]"
    >
      <Input aria-label="公司名称" placeholder="请输入公司名称" />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">提交</Button>
    </FormItem>
    <div class="demo-dynamic-result">
      {{ submitted ? `提交结果：${submitted}` : '切换账号类型，观察公司名称字段的动态出现。' }}
    </div>
  </Form>
</template>

<style scoped>
.demo-dynamic-result {
  padding: 8px 12px;
  color: var(--apollo-color-text-secondary);
  background: var(--apollo-color-fill-alter);
  border-radius: 6px;
  word-break: break-all;
}
</style>
```

## 动态增减表单项 (dynamic-form-items)

`Form.List` 的默认插槽接收 `{ fields, operations, meta }`：`fields` 用于 `v-for` 渲染行，`operations.add` / `operations.remove` / `operations.move` 负责增删与排序，`meta.errors` 汇总列表级校验错误。行内 `Form.Item` 使用 `[field.name, 'name']` 这样的数组 `name` 与列表项绑定。

### dynamic-form-items.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/dynamic-form-items.tsx：Form.List 的增删、排序与 meta.errors。
import {
  ArrowDownOutlined,
  ArrowUpOutlined,
  MinusCircleOutlined,
  PlusOutlined,
} from '@apollo-design/icons';
import { Button, Flex, Form, FormItem, FormList, Input, useForm } from '@apollo-design/ui';
import { ref } from 'vue';

const [form] = useForm();
const submitted = ref('');

const initialValues = {
  passengers: [{ name: 'Apollo' }],
};

const onFinish = (values: unknown) => {
  submitted.value = JSON.stringify(values);
};
</script>

<template>
  <Form :form="form" :initial-values="initialValues" layout="vertical" @finish="onFinish">
    <FormList name="passengers">
      <template #default="{ fields, operations, meta }">
        <Flex
          v-for="field in fields"
          :key="field.key"
          align="flex-start"
          gap="small"
          class="demo-list-row"
        >
          <FormItem
            :name="[field.name, 'name']"
            label="乘客姓名"
            :rules="[{ required: true, message: '请输入乘客姓名' }]"
            style="flex: 1"
          >
            <Input aria-label="乘客姓名" placeholder="请输入乘客姓名" />
          </FormItem>
          <Button
            type="text"
            :icon="ArrowUpOutlined"
            aria-label="上移该行"
            :disabled="field.name === 0"
            style="margin-top: 30px"
            @click="operations.move(field.name, field.name - 1)"
          />
          <Button
            type="text"
            :icon="ArrowDownOutlined"
            aria-label="下移该行"
            :disabled="field.name === fields.length - 1"
            style="margin-top: 30px"
            @click="operations.move(field.name, field.name + 1)"
          />
          <Button
            type="text"
            danger
            :icon="MinusCircleOutlined"
            aria-label="删除该行"
            :disabled="fields.length === 1"
            style="margin-top: 30px"
            @click="operations.remove(field.name)"
          />
        </Flex>
        <div v-if="meta.errors?.length" class="demo-list-errors">
          列表级错误：{{ meta.errors.map(String).join('；') }}
        </div>
        <FormItem>
          <Button type="dashed" block :icon="PlusOutlined" @click="operations.add()">
            添加乘客
          </Button>
        </FormItem>
      </template>
    </FormList>
    <FormItem>
      <Button type="primary" html-type="submit">提交</Button>
    </FormItem>
    <div class="demo-list-result">
      {{ submitted ? `提交结果：${submitted}` : '使用行内按钮调整顺序或增删乘客。' }}
    </div>
  </Form>
</template>

<style scoped>
.demo-list-row {
  margin-bottom: 8px;
}

.demo-list-errors {
  margin-bottom: 8px;
  color: #ff4d4f;
}

.demo-list-result {
  padding: 8px 12px;
  color: var(--apollo-color-text-secondary);
  background: var(--apollo-color-fill-alter);
  border-radius: 6px;
  word-break: break-all;
}
</style>
```

## 动态校验规则 (dynamic-rule)

`rules` 可以是 `computed` 计算出的数组。示例用 `Switch` 切换「普通 / 严格」模式：严格模式追加最小长度与「字母 + 数字」正则规则，`Form.Item` 会在下一次校验时立即使用新规则。`Switch` 带 `aria-label`，保证可访问名称。

### dynamic-rule.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/dynamic-rule.tsx：按开关动态切换校验规则。
import type { FormItemProps } from '@apollo-design/ui';
import { Button, Form, FormItem, Input, Switch, useForm } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const [form] = useForm();
const strict = ref(false);
const submitted = ref('');

const rules = computed<FormItemProps['rules']>(() =>
  strict.value
    ? [
        { required: true, message: '请输入密码' },
        { min: 8, message: '严格模式下密码至少 8 位' },
        { pattern: /^(?=.*[A-Za-z])(?=.*\d).+$/, message: '严格模式下必须同时包含字母和数字' },
      ]
    : [{ required: true, message: '请输入密码' }],
);

const onFinish = (values: unknown) => {
  submitted.value = JSON.stringify(values);
};
</script>

<template>
  <Form :form="form" layout="vertical" @finish="onFinish">
    <div class="demo-rule-switch">
      <Switch v-model:checked="strict" aria-label="严格校验模式" />
      <span>{{ strict ? '严格模式：至少 8 位且包含字母与数字' : '普通模式：仅必填' }}</span>
    </div>
    <FormItem label="密码" name="password" :rules="rules">
      <Input
        aria-label="密码"
        type="password"
        placeholder="请输入密码"
        autocomplete="new-password"
      />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">提交</Button>
    </FormItem>
    <div class="demo-rule-result">
      {{ submitted ? `提交结果：${submitted}` : '切换开关后再次提交，校验规则会立即变化。' }}
    </div>
  </Form>
</template>

<style scoped>
.demo-rule-switch {
  display: flex;
  gap: 8px;
  align-items: center;
  margin-bottom: 16px;
}

.demo-rule-result {
  padding: 8px 12px;
  color: var(--apollo-color-text-secondary);
  background: var(--apollo-color-fill-alter);
  border-radius: 6px;
  word-break: break-all;
}
</style>
```

## 表单上下文 (form-context)

在 `Form` 的后代组件中调用 `useWatch('username')` 时无需显式传入 `form` 实例：`useWatch` 会通过 `Form` 提供的上下文字段自动订阅。示例中的 `WatchDisplay` 是一个独立子组件，用来证明「不传 form 也能读到最新值」。

### form-context.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/form-context.tsx：
// 子组件不传 form 实例，useWatch 通过 Form 提供的上下文自动读取字段。
import { Form, FormItem, Input, useWatch } from '@apollo-design/ui';
import { defineComponent, h } from 'vue';

const WatchDisplay = defineComponent({
  name: 'WatchDisplay',
  setup() {
    const username = useWatch('username');
    return () =>
      h(
        'div',
        { class: 'demo-context-value' },
        `子组件通过上下文读取 username：${username.value ?? '（空）'}`,
      );
  },
});
</script>

<template>
  <Form :initial-values="{ username: '' }" layout="vertical">
    <FormItem label="用户名" name="username">
      <Input aria-label="用户名" placeholder="请输入用户名" />
    </FormItem>
    <WatchDisplay />
    <p class="demo-context-tip">
      子组件没有接收 form 参数，`useWatch` 仍然能从 FormContext 读取到最新值。
    </p>
  </Form>
</template>

<style scoped>
.demo-context-value {
  padding: 8px 12px;
  color: #1677ff;
  background: rgb(22 119 255 / 6%);
  border-radius: 6px;
}

.demo-context-tip {
  margin: 8px 0 0;
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

## 弹窗表单 (form-in-modal)

把 `Form` 放进 `Modal`，在 `@ok` 中调用 `form.validateFields()`：校验通过后关闭弹窗并展示提交结果，校验失败则保持弹窗打开，由 `Form.Item` 显示错误。`Modal` 的 `closable` 传入带 `aria-label` 的对象，保证关闭按钮有可访问名称。

### form-in-modal.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/form-in-modal.tsx：Modal 中点「确定」时先校验表单。
import { Alert, Button, Form, FormItem, Input, Modal, useForm } from '@apollo-design/ui';
import { ref } from 'vue';

const [form] = useForm();
const open = ref(false);
const submitted = ref('');

const openModal = () => {
  form.resetFields();
  submitted.value = '';
  open.value = true;
};

const handleOk = async () => {
  try {
    const values = await form.validateFields();
    submitted.value = JSON.stringify(values);
    open.value = false;
  } catch {
    // 校验失败时保持弹窗打开，由 Form.Item 展示错误信息。
  }
};

const handleCancel = () => {
  open.value = false;
};
</script>

<template>
  <div class="demo-modal-trigger">
    <Button type="primary" @click="openModal">打开表单弹窗</Button>
    <Alert
      v-if="submitted"
      type="success"
      show-icon
      title="表单已提交"
      :description="submitted"
    />
  </div>

  <Modal
    title="新建项目"
    :open="open"
    :closable="{ 'aria-label': '关闭弹窗' }"
    @ok="handleOk"
    @cancel="handleCancel"
  >
    <Form :form="form" layout="vertical">
      <FormItem
        label="项目名称"
        name="projectName"
        :rules="[{ required: true, message: '请输入项目名称' }]"
      >
        <Input aria-label="项目名称" placeholder="请输入项目名称" />
      </FormItem>
      <FormItem
        label="负责人邮箱"
        name="ownerEmail"
        :rules="[
          { required: true, message: '请输入负责人邮箱' },
          { type: 'email', message: '邮箱格式不正确' },
        ]"
      >
        <Input aria-label="负责人邮箱" placeholder="name@example.com" />
      </FormItem>
    </Form>
  </Modal>
</template>

<style scoped>
.demo-modal-trigger {
  display: flex;
  flex-direction: column;
  gap: 12px;
  align-items: flex-start;
}
</style>
```

## 嵌套路径 (form-item-path)

`Form.Item` 的 `name` 支持数组路径，例如 `['user', 'name']` 与 `['user', 'email']`，它们会映射到 `{ user: { name, email } }`。`useWatch(['user', 'name'], form)` 订阅嵌套值，`setFieldsValue({ user: { ... } })` 可以一次写入整棵子树。

### form-item-path.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/form-item-path.tsx：用数组 namePath 读写嵌套字段。
import { Button, Form, FormItem, Input, Space, useForm, useWatch } from '@apollo-design/ui';
import { ref } from 'vue';

const [form] = useForm();
const name = useWatch(['user', 'name'], form);
const email = useWatch(['user', 'email'], form);
const snapshot = ref('');

const fillNested = () => {
  form.setFieldsValue({ user: { name: 'Apollo', email: 'apollo@example.com' } });
};

const readNested = () => {
  snapshot.value = JSON.stringify(form.getFieldsValue(true));
};
</script>

<template>
  <Form :form="form" :initial-values="{ user: { name: '', email: '' } }" layout="vertical">
    <FormItem
      label="用户名（user.name）"
      :name="['user', 'name']"
      :rules="[{ required: true, message: '请输入用户名' }]"
    >
      <Input aria-label="用户名" placeholder="请输入用户名" />
    </FormItem>
    <FormItem
      label="邮箱（user.email）"
      :name="['user', 'email']"
      :rules="[
        { required: true, message: '请输入邮箱' },
        { type: 'email', message: '邮箱格式不正确' },
      ]"
    >
      <Input aria-label="邮箱" placeholder="name@example.com" />
    </FormItem>
    <FormItem>
      <Space wrap>
        <Button @click="fillNested">setFieldsValue 嵌套对象</Button>
        <Button type="primary" @click="readNested">读取整棵值树</Button>
      </Space>
    </FormItem>
    <div class="demo-path-preview">
      <div>useWatch(['user', 'name']) = {{ name ?? '（空）' }}</div>
      <div>useWatch(['user', 'email']) = {{ email ?? '（空）' }}</div>
      <pre v-if="snapshot">{{ snapshot }}</pre>
    </div>
  </Form>
</template>

<style scoped>
.demo-path-preview {
  display: flex;
  flex-direction: column;
  gap: 4px;
  padding: 8px 12px;
  color: var(--apollo-color-text-secondary);
  background: var(--apollo-color-fill-alter);
  border-radius: 6px;
  word-break: break-all;
}

.demo-path-preview pre {
  margin: 4px 0 0;
  white-space: pre-wrap;
}
</style>
```

## 标签换行 (layout-can-wrap)

`Form` 的 `label-wrap` 控制水平布局下标签是否允许换行；配合 `label-col` / `wrapper-col` 的栅格比例，可以处理超长标签。示例用 `Switch` 实时切换 `label-wrap`，并在页面中显示当前状态。

### layout-can-wrap.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/layout-can-wrap.tsx：labelWrap 与 labelCol / wrapperCol 的配合。
import { Button, Form, FormItem, Input, Switch } from '@apollo-design/ui';
import { ref } from 'vue';

const labelWrap = ref(false);
</script>

<template>
  <div>
    <div class="demo-wrap-switch">
      <Switch v-model:checked="labelWrap" aria-label="标签换行" />
      <span>labelWrap：{{ labelWrap ? '开启' : '关闭' }}</span>
    </div>
    <Form
      layout="horizontal"
      :label-wrap="labelWrap"
      :label-col="{ span: 6 }"
      :wrapper-col="{ span: 18 }"
    >
      <FormItem
        label="这是一个很长很长、需要根据 labelWrap 决定是否换行的字段标签"
        name="longLabel"
        :rules="[{ required: true, message: '请输入内容' }]"
      >
        <Input aria-label="长标签字段" placeholder="切换 labelWrap 观察标签布局" />
      </FormItem>
      <FormItem label="普通标签" name="normalLabel">
        <Input aria-label="普通标签字段" placeholder="普通标签" />
      </FormItem>
      <FormItem :wrapper-col="{ span: 18, offset: 6 }">
        <Button type="primary" html-type="submit">提交</Button>
      </FormItem>
    </Form>
  </div>
</template>

<style scoped>
.demo-wrap-switch {
  display: flex;
  gap: 8px;
  align-items: center;
  margin-bottom: 16px;
}
</style>
```

## 多种布局 (layout-multiple)

同一页面可以并列多个 `Form`，分别设置 `layout="inline"`、`layout="horizontal"` 与 `layout="vertical"`。水平布局使用 `label-col` / `wrapper-col` 控制标签与控件的栅格占比；各表单拥有独立的内部 store，字段名互不影响。

### layout-multiple.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/layout-multiple.tsx：同一页面并列三种 layout。
import { Button, Form, FormItem, Input } from '@apollo-design/ui';
</script>

<template>
  <div class="demo-layout-list">
    <section>
      <h4>Inline</h4>
      <Form layout="inline">
        <FormItem label="用户名" name="inlineUser">
          <Input aria-label="inline 用户名" placeholder="Username" />
        </FormItem>
        <FormItem label="密码" name="inlinePassword">
          <Input
            aria-label="inline 密码"
            type="password"
            placeholder="Password"
            autocomplete="new-password"
          />
        </FormItem>
        <FormItem>
          <Button type="primary" html-type="submit">登录</Button>
        </FormItem>
      </Form>
    </section>

    <section>
      <h4>Horizontal</h4>
      <Form layout="horizontal" :label-col="{ span: 6 }" :wrapper-col="{ span: 18 }">
        <FormItem label="用户名" name="horizontalUser">
          <Input aria-label="horizontal 用户名" placeholder="Username" />
        </FormItem>
        <FormItem label="密码" name="horizontalPassword">
          <Input
            aria-label="horizontal 密码"
            type="password"
            placeholder="Password"
            autocomplete="new-password"
          />
        </FormItem>
      </Form>
    </section>

    <section>
      <h4>Vertical</h4>
      <Form layout="vertical">
        <FormItem label="用户名" name="verticalUser">
          <Input aria-label="vertical 用户名" placeholder="Username" />
        </FormItem>
        <FormItem label="密码" name="verticalPassword">
          <Input
            aria-label="vertical 密码"
            type="password"
            placeholder="Password"
            autocomplete="new-password"
          />
        </FormItem>
      </Form>
    </section>
  </div>
</template>

<style scoped>
.demo-layout-list {
  display: flex;
  flex-direction: column;
  gap: 24px;
}

.demo-layout-list h4 {
  margin: 0 0 12px;
}
</style>
```

## 登录表单 (login)

一个完整的登录场景：`Form.Item` 的 `rules` 校验用户名与密码，`Checkbox` 通过 `value-prop-name="checked"` 与布尔字段绑定，提交后由 `@finish` 展示欢迎信息。`Input` 使用 `autocomplete` 与 `aria-label` 兼顾浏览器自动填充与可访问性。

### login.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/login.tsx：登录表单、记住我与成功反馈。
import { Alert, Button, Checkbox, Form, FormItem, Input } from '@apollo-design/ui';
import { ref } from 'vue';

const success = ref('');

const onFinish = (values: unknown) => {
  const data = values as { username?: string; remember?: boolean };
  success.value = `欢迎回来，${data.username ?? '访客'}！记住我：${data.remember ? '是' : '否'}`;
};
</script>

<template>
  <Form
    name="login"
    :initial-values="{ remember: true }"
    layout="vertical"
    style="max-width: 360px"
    @finish="onFinish"
  >
    <FormItem
      label="用户名"
      name="username"
      :rules="[{ required: true, message: '请输入用户名' }]"
    >
      <Input aria-label="用户名" placeholder="用户名" autocomplete="username" />
    </FormItem>
    <FormItem
      label="密码"
      name="password"
      :rules="[{ required: true, message: '请输入密码' }]"
    >
      <Input
        aria-label="密码"
        type="password"
        placeholder="密码"
        autocomplete="current-password"
      />
    </FormItem>
    <FormItem name="remember" value-prop-name="checked">
      <Checkbox>记住我</Checkbox>
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit" block>登录</Button>
    </FormItem>
  </Form>
  <Alert v-if="success" type="success" show-icon :title="success" class="demo-login-alert" />
</template>

<style scoped>
.demo-login-alert {
  max-width: 360px;
  margin-top: 16px;
}
</style>
```

## 嵌套校验消息 (nest-messages)

`Form` 的 `validate-messages` 支持按规则类型嵌套覆盖默认文案：`required`、`types.email`、`string.min`、`number.min` 分别对应不同校验失败场景。模板变量如 `${name}`、`${min}` 会在运行时替换为字段名和规则参数。

### nest-messages.vue

```vue
<script setup lang="ts">
// biome-ignore-all lint/suspicious/noTemplateCurlyInString: validateMessages 的 `${name}` / `${min}` 是运行时占位符，必须保持字面量。
// 对齐 antd 的 demo/nest-messages.tsx：Form 级 validateMessages 的嵌套模板。
import type { ValidateErrorEntity } from '@apollo-design/form-core';
import type { FormProps } from '@apollo-design/ui';
import { Alert, Button, Form, FormItem, Input, InputNumber } from '@apollo-design/ui';
import { ref } from 'vue';

const messages: NonNullable<FormProps['validateMessages']> = {
  required: "'${name}' 是必填项",
  types: {
    email: "'${name}' 不是有效的邮箱地址",
  },
  string: {
    min: "'${name}' 至少需要 ${min} 个字符",
  },
  number: {
    min: "'${name}' 不能小于 ${min}",
  },
};

const feedback = ref('');
const failed = ref(false);

const onFinish = (values: unknown) => {
  failed.value = false;
  feedback.value = `提交成功：${JSON.stringify(values)}`;
};

const onFinishFailed = (errorInfo: ValidateErrorEntity) => {
  failed.value = true;
  feedback.value = errorInfo.errorFields
    .map((field) => `${field.name.join('.')}：${field.errors.join('、')}`)
    .join('；');
};
</script>

<template>
  <Form
    layout="vertical"
    :validate-messages="messages"
    @finish="onFinish"
    @finish-failed="onFinishFailed"
  >
    <FormItem label="用户名" name="username" :rules="[{ required: true }]">
      <Input aria-label="用户名" placeholder="请输入用户名" />
    </FormItem>
    <FormItem
      label="邮箱"
      name="email"
      :rules="[{ required: true }, { type: 'email' }]"
    >
      <Input aria-label="邮箱" placeholder="name@example.com" />
    </FormItem>
    <FormItem
      label="年龄"
      name="age"
      :rules="[{ required: true }, { type: 'number', min: 18 }]"
    >
      <InputNumber aria-label="年龄" :min="0" style="width: 160px" />
    </FormItem>
    <FormItem
      label="密码"
      name="password"
      :rules="[{ required: true }, { min: 6 }]"
    >
      <Input
        aria-label="密码"
        type="password"
        placeholder="至少 6 个字符"
        autocomplete="new-password"
      />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">提交</Button>
    </FormItem>
    <Alert
      v-if="feedback"
      :type="failed ? 'error' : 'success'"
      show-icon
      :title="failed ? '校验失败' : '校验通过'"
      :description="feedback"
    />
  </Form>
</template>
```

## 必填标记 (required-mark)

`Form` 的 `required-mark` 接受 `true`、`false` 或 `'optional'`。自定义内容使用 `#requiredMark="{ label, required }"`，其中 `label` 是保留原标签内容的稳定组件，可用 `<component :is="label" />` 渲染。示例可实时切换默认标记、隐藏、optional 与自定义插槽。

### required-mark.vue

```vue
<script setup lang="ts">
import type { RequiredMark } from '@apollo-design/ui';
import { Button, Form, FormItem, Input, Radio, RadioGroup } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const markMode = ref<'required' | 'hidden' | 'optional' | 'custom'>('required');

const requiredMark = computed<RequiredMark>(() => {
  if (markMode.value === 'optional') return 'optional';
  return markMode.value === 'required';
});
</script>

<template>
  <div class="demo-mark-switch">
    <RadioGroup v-model:value="markMode" aria-label="必填标记模式">
      <Radio value="required">显示必填星号</Radio>
      <Radio value="hidden">隐藏必填标记</Radio>
      <Radio value="optional">显示 optional</Radio>
      <Radio value="custom">自定义插槽</Radio>
    </RadioGroup>
  </div>
  <Form :required-mark="requiredMark" layout="vertical" style="max-width: 420px">
    <template v-if="markMode === 'custom'" #requiredMark="{ label, required }">
      <component :is="label" />
      <span class="demo-custom-mark">{{ required ? '必填' : '选填' }}</span>
    </template>
    <FormItem
      label="用户名"
      name="username"
      :rules="[{ required: true, message: '请输入用户名' }]"
    >
      <Input aria-label="用户名" placeholder="必填字段" />
    </FormItem>
    <FormItem label="昵称" name="nickname">
      <Input aria-label="昵称" placeholder="可选字段" />
    </FormItem>
    <FormItem
      label="邮箱"
      name="email"
      :rules="[{ required: true, message: '请输入邮箱' }]"
    >
      <Input aria-label="邮箱" placeholder="必填字段" />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">提交</Button>
    </FormItem>
  </Form>
</template>

<style scoped>
.demo-mark-switch {
  margin-bottom: 16px;
}
.demo-custom-mark {
  margin-inline-start: 8px;
  color: #722ed1;
  font-size: 12px;
}
</style>
```

## 语义化结构样式 (style-class)

通过 `Form` 的 `classNames` 与 `styles` 可以分别定制 `root` / `label` / `content` / `help` / `helpItem` / `extra` 六个语义槽。示例同时演示 `Form.Item` 的 `help` 与 `extra`，并用全局样式类覆盖 label 颜色、内容区背景、帮助文字与补充说明。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/style-class.tsx：Form 的 label / content / help / extra 语义槽。
import type { FormSemanticClassNames, FormSemanticStyles } from '@apollo-design/ui';
import { Button, Form, FormItem, Input, Select } from '@apollo-design/ui';

const classNames: FormSemanticClassNames = {
  root: 'demo-form-root',
  label: 'demo-form-label',
  content: 'demo-form-content',
  help: 'demo-form-help',
  helpItem: 'demo-form-help-item',
  extra: 'demo-form-extra',
};

const styles: FormSemanticStyles = {
  label: { fontWeight: 600 },
  content: { maxWidth: '360px' },
  help: { paddingInlineStart: '8px' },
  extra: { color: '#1677ff' },
};

const roleOptions = [
  { value: 'admin', label: '管理员' },
  { value: 'member', label: '成员' },
];
</script>

<template>
  <Form
    :class-names="classNames"
    :styles="styles"
    layout="vertical"
    :initial-values="{ role: 'member' }"
  >
    <FormItem
      label="用户名"
      name="username"
      validate-status="error"
      help="用户名已被占用（help 语义槽）"
      extra="这是 extra 语义槽，可通过 classNames.extra / styles.extra 定制。"
      :rules="[{ required: true, message: '请输入用户名' }]"
    >
      <Input aria-label="用户名" placeholder="请输入用户名" />
    </FormItem>
    <FormItem label="角色" name="role">
      <Select aria-label="角色" :options="roleOptions" />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">提交</Button>
    </FormItem>
  </Form>
</template>

<style scoped>
.demo-form-root {
  padding: 16px;
  border: 1px dashed #d9d9d9;
  border-radius: 8px;
}
</style>

<style>
.demo-form-label {
  color: #722ed1 !important;
}

.demo-form-content {
  background: rgb(114 46 209 / 4%);
}

.demo-form-help-item {
  font-style: italic;
}

.demo-form-extra {
  font-size: 12px;
}
</style>
```

## 时间类控件 (time-related-controls)

`DatePicker`、`TimePicker` 与 `DatePicker.RangePicker` 都可以直接作为 `Form.Item` 的控件，表单会注入 `value` 与更新事件。示例用 `useWatch` 实时回显日期、时间与区间值，提交时由 `@finish` 输出完整表单数据。

### time-related-controls.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/time-related-controls.tsx：
// DatePicker / TimePicker / RangePicker 作为 Form.Item 控件时的取值与回显。
import {
  Button,
  DatePicker,
  Form,
  FormItem,
  TimePicker,
  useForm,
  useWatch,
} from '@apollo-design/ui';
import { ref } from 'vue';

const [form] = useForm();
const dateValue = useWatch('date', form);
const timeValue = useWatch('time', form);
const rangeValue = useWatch('range', form);
const submitted = ref('');

const formatValue = (value: unknown): string => {
  if (value === null || value === undefined) return '（空）';
  if (Array.isArray(value)) {
    return value.map((item) => String(item)).join(' → ');
  }
  return String(value);
};

const onFinish = (values: unknown) => {
  submitted.value = JSON.stringify(values);
};
</script>

<template>
  <Form :form="form" layout="vertical" @finish="onFinish">
    <FormItem label="日期时间" name="date">
      <DatePicker show-time format="YYYY-MM-DD HH:mm" placeholder="请选择日期时间" />
    </FormItem>
    <FormItem label="时间" name="time">
      <TimePicker format="HH:mm" placeholder="请选择时间" />
    </FormItem>
    <FormItem label="日期区间" name="range">
      <DatePicker.RangePicker :placeholder="['开始日期', '结束日期']" />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">提交</Button>
    </FormItem>
    <div class="demo-time-preview">
      <div>date = {{ formatValue(dateValue) }}</div>
      <div>time = {{ formatValue(timeValue) }}</div>
      <div>range = {{ formatValue(rangeValue) }}</div>
      <div v-if="submitted">提交结果：{{ submitted }}</div>
    </div>
  </Form>
</template>

<style scoped>
.demo-time-preview {
  display: flex;
  flex-direction: column;
  gap: 4px;
  padding: 8px 12px;
  color: var(--apollo-color-text-secondary);
  background: var(--apollo-color-fill-alter);
  border-radius: 6px;
  word-break: break-all;
}
</style>
```

## 表单变体 (variant)

`Form` 的 `variant` 会向下传导给输入控件，可选 `outlined`、`borderless`、`filled`、`underlined`。示例用 `RadioGroup` 切换变体，`Input` 与 `Select` 会同步更新视觉样式。

### variant.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/variant.tsx：Form 级 variant 传导到所有输入控件。
import { Button, Form, FormItem, Input, Radio, RadioGroup, Select } from '@apollo-design/ui';
import { ref } from 'vue';

const variant = ref<'outlined' | 'borderless' | 'filled' | 'underlined'>('outlined');

const teamOptions = [
  { value: 'design', label: '设计团队' },
  { value: 'engineer', label: '工程团队' },
];
</script>

<template>
  <div class="demo-variant-switch">
    <RadioGroup v-model:value="variant" aria-label="表单变体">
      <Radio value="outlined">outlined</Radio>
      <Radio value="borderless">borderless</Radio>
      <Radio value="filled">filled</Radio>
      <Radio value="underlined">underlined</Radio>
    </RadioGroup>
  </div>
  <Form :variant="variant" layout="vertical" style="max-width: 420px">
    <FormItem label="用户名" name="username">
      <Input aria-label="用户名" placeholder="请输入用户名" />
    </FormItem>
    <FormItem label="团队" name="team">
      <Select aria-label="团队" placeholder="请选择团队" :options="teamOptions" />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">提交</Button>
    </FormItem>
  </Form>
</template>

<style scoped>
.demo-variant-switch {
  margin-bottom: 16px;
}
</style>
```

## 仅警告校验 (warning-only)

在规则上设置 `warningOnly: true` 后，校验失败只会进入 `meta.warnings` 并展示警告，不会阻止 `@finish`。示例把「用户名」设为普通必填规则、把「昵称」设为仅警告规则，提交后可观察到两者对提交结果的差异。

### warning-only.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/warning-only.tsx：warningOnly 规则只提示、不阻断提交。
import type { ValidateErrorEntity } from '@apollo-design/form-core';
import { Alert, Button, Form, FormItem, Input, useForm } from '@apollo-design/ui';
import { ref } from 'vue';

const [form] = useForm();
const feedback = ref('');
const failed = ref(false);

const onFinish = (values: unknown) => {
  failed.value = false;
  feedback.value = `提交成功：${JSON.stringify(values)}`;
};

const onFinishFailed = (errorInfo: ValidateErrorEntity) => {
  failed.value = true;
  feedback.value = `提交被阻断：${errorInfo.errorFields
    .map((field) => field.errors.join('、'))
    .join('；')}`;
};
</script>

<template>
  <Form :form="form" layout="vertical" @finish="onFinish" @finish-failed="onFinishFailed">
    <FormItem
      label="用户名（必填）"
      name="username"
      :rules="[{ required: true, message: '请输入用户名' }]"
    >
      <Input aria-label="用户名" placeholder="不填会阻断提交" />
    </FormItem>
    <FormItem
      label="昵称（建议填写）"
      name="nickname"
      :rules="[{ required: true, warningOnly: true, message: '建议填写昵称' }]"
    >
      <Input aria-label="昵称" placeholder="不填只会出现警告" />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">提交</Button>
    </FormItem>
    <Alert
      v-if="feedback"
      :type="failed ? 'error' : 'success'"
      show-icon
      :title="failed ? '提交失败' : '提交成功'"
      :description="feedback"
    />
  </Form>
</template>
```

## 无表单实例 (without-form-create)

不调用 `useForm()` 时，`Form` 会自动创建一个内部 store，`Form.Item` 的注入与 `@finish` 仍然正常工作。示例通过改变 `key` 重新挂载表单来实现重置，并展示 `@finish` 收集到的字段值。

### without-form-create.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/without-form-create.tsx：
// 不调用 useForm，Form 自己创建内部 store；通过 key 重新挂载来重置。
import { Alert, Button, Form, FormItem, Input, Select, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const formKey = ref(0);
const submitted = ref('');

const departmentOptions = [
  { value: 'design', label: '设计部' },
  { value: 'engineering', label: '工程部' },
];

const onFinish = (values: unknown) => {
  submitted.value = JSON.stringify(values);
};

const reset = () => {
  submitted.value = '';
  formKey.value += 1;
};
</script>

<template>
  <Form :key="formKey" layout="vertical" @finish="onFinish">
    <FormItem
      label="姓名"
      name="name"
      :rules="[{ required: true, message: '请输入姓名' }]"
    >
      <Input aria-label="姓名" placeholder="请输入姓名" />
    </FormItem>
    <FormItem label="部门" name="department">
      <Select aria-label="部门" placeholder="请选择部门" :options="departmentOptions" />
    </FormItem>
    <FormItem>
      <Space wrap>
        <Button type="primary" html-type="submit">提交</Button>
        <Button @click="reset">重置（重新挂载）</Button>
      </Space>
    </FormItem>
    <Alert
      v-if="submitted"
      type="success"
      show-icon
      title="表单提交成功"
      :description="submitted"
    />
  </Form>
</template>
```

## basic (basic)

最基础的表单：`Form.Item` 包裹控件，`rules` 声明校验。\n

### basic.vue

```vue
<script setup lang="ts">
import { Button, Form, FormItem, Input, useForm } from '@apollo-design/ui';
import { reactive } from 'vue';

const formState = reactive({ name: '', password: '' });
const [formRef] = useForm();

const onFinish = (values: unknown) => {
  console.log('Success:', values);
};
</script>

<template>
  <Form :model="formState" :form="formRef" @finish="onFinish">
    <FormItem label="Username" name="name" :rules="[{ required: true, message: '请输入用户名' }]">
      <Input v-model:value="formState.name" placeholder="Username" />
    </FormItem>
    <FormItem label="Password" name="password" :rules="[{ required: true, message: '请输入密码' }]">
      <Input v-model:value="formState.password" type="password" placeholder="Password" />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">Log in</Button>
    </FormItem>
  </Form>
</template>
```

## customized-form-controls (customized-form-controls)

内联表单与提交按钮（`html-type="submit"`）。\n

### customized-form-controls.vue

```vue
<script setup lang="ts">
import { Button, Form, FormItem, Input, useForm } from '@apollo-design/ui';
import { reactive } from 'vue';

const formState = reactive({ name: '', url: '' });
const [formRef] = useForm();
</script>

<template>
  <Form :model="formState" :form="formRef" layout="inline">
    <FormItem name="url" :rules="[{ required: true }]">
      <Input v-model:value="formState.url" placeholder="url" />
    </FormItem>
    <FormItem>
      <Button type="primary" html-type="submit">Submit</Button>
    </FormItem>
  </Form>
</template>
```

## label (label)

label 定制：required 标记 / optional 文案 / 无 label（control 顶格）/ 无冒号 / tooltip。\n

### label.vue

```vue
<script setup lang="ts">
import { Form, FormItem, Input } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
</script>

<template>
  <Form>
    <FormItem label="required mark" name="a" required>
      <Input v-model:value="value" />
    </FormItem>
    <FormItem label="optional mark" name="b" required-mark="optional">
      <Input v-model:value="value" />
    </FormItem>
    <FormItem :label="null" name="c" :label-col="{ span: 4 }">
      <!-- ⚠️ 无 label 的字段：控件必须自带可访问名（axe 的 label 规则会把
           「既无 label 关联又无 aria-label」判成 violation，本 demo 因此显式补上） -->
      <Input v-model:value="value" aria-label="no label" />
    </FormItem>
    <FormItem label="no colon" name="d" :colon="false">
      <Input v-model:value="value" />
    </FormItem>
    <FormItem label="tooltip" name="e" :tooltip="'这是一段说明'">
      <Input v-model:value="value" />
    </FormItem>
  </Form>
</template>
```

## layout (layout)

三种布局：`horizontal` / `vertical` / `inline`。\n

### layout.vue

```vue
<script setup lang="ts">
import { Form, FormItem, Input, Radio, RadioGroup } from '@apollo-design/ui';
import { reactive, ref } from 'vue';

const formState = reactive({ name: '' });
const layout = ref<'horizontal' | 'vertical' | 'inline'>('horizontal');
</script>

<template>
  <Form :layout="layout" :model="formState">
    <FormItem label="Layout" name="layout">
      <RadioGroup v-model:value="layout">
        <Radio value="horizontal">horizontal</Radio>
        <Radio value="vertical">vertical</Radio>
        <Radio value="inline">inline</Radio>
      </RadioGroup>
    </FormItem>
    <FormItem label="Name" name="name">
      <Input v-model:value="formState.name" placeholder="Name" />
    </FormItem>
  </Form>
</template>
```

## validate-status (validate-status)

校验状态（`validateStatus` + `hasFeedback`）：错误/警告/校验中。\n

### validate-status.vue

```vue
<script setup lang="ts">
import { Form, FormItem, Input } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
</script>

<template>
  <Form layout="vertical">
    <FormItem label="Error" name="err" validate-status="error" help="出错信息" has-feedback>
      <Input v-model:value="value" placeholder="error" />
    </FormItem>
    <FormItem label="Warning" name="warn" validate-status="warning" help="警告信息" has-feedback>
      <Input v-model:value="value" placeholder="warning" />
    </FormItem>
    <FormItem label="Validating" name="val" validate-status="validating" help="校验中" has-feedback>
      <Input v-model:value="value" placeholder="validating" />
    </FormItem>
  </Form>
</template>
```

---

# Grid

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/grid


24 栅格布局。Row 建立 flex 行，Col 表达列宽、顺序、逻辑偏移和 flex 填充。列应属于 Row 的布局；包装组件可正常透传插槽及注入，嵌套 Row 使用自己的 gutter。

## 代码演示

[`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/grid/demo) 的 13 个实际 Demo 覆盖基础栅格、双轴间距、偏移/排序、六种主轴对齐、四种交叉轴对齐、flex、响应式与原生范围控件。色块使用主题背景和文字变量。

## API

### Row

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| gutter | 非负间距；数字为 px，字符串为有效 CSS 长度。两个轴都可使用断点对象 | `ResponsiveValue<number \| string> \| readonly [ResponsiveValue<number \| string>, ResponsiveValue<number \| string>]` | `0` |
| justify | 主轴对齐，支持断点对象 | `ResponsiveValue<'start' \| 'end' \| 'center' \| 'space-around' \| 'space-between' \| 'space-evenly'>` | — |
| align | 交叉轴对齐，支持断点对象；stretch 显式拉伸列盒 | `ResponsiveValue<'top' \| 'middle' \| 'bottom' \| 'stretch'>` | — |
| wrap | 自动换行；未传或 true 换行，false 使用 nowrap | `boolean` | `true` |
| prefixCls | 根类名前缀；自定义前缀需自行提供对应静态 CSS | `string` | Provider 前缀 + `-row`，默认 `apollo-row` |

`ResponsiveValue<T> = T | Partial<Record<Breakpoint, T>>`。

### Col

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| span | 占用 0–24 个整数栅格；0 隐藏列 | `number` | — |
| order | 排列顺序，0–24 整数 | `number` | — |
| offset | 行内起始方向的间隔栅格数，0–24 整数 | `number` | — |
| push / pull | 沿行内起始/结束方向移动的栅格数，0–24 整数 | `number` | — |
| flex | auto→`1 1 auto`；数字 n→`n n auto`（含 0/分数）；px/em/rem/% 长度→`0 0 长度`；其他有效 flex 字符串原样消费 | `string \| number` | — |
| xs / sm / md / lg / xl / xxl / xxxl | 响应式数字 span 简写，或包含 span/order/offset/push/pull/flex 的对象 | `number \| ColSize` | — |
| prefixCls | 根类名前缀；自定义前缀需自行提供对应静态 CSS | `string` | Provider 前缀 + `-col`，默认 `apollo-col` |

### 默认插槽、原生 attrs 与 ref

Row、Col 的默认插槽无作用域参数，接受完整 Vue 内容（文本、0、多节点、Fragment 和组件）；无业务 emits 或 v-model。根均为稳定的 div，原生 `id`、`class`、`style`、ARIA、tabindex 和 DOM 监听器落在这个根上，监听器只触发一次。根 `style` 支持 Vue 字符串、对象和数组，替换/移除实时生效。

- Row 样式优先级：gutter 几何 → Provider `row.style` → 原生 `style`。
- Col 样式优先级：gutter/flex 几何 → Provider `col.style` → 原生 `style` → 响应式 flex 变量。显式 style 可覆盖几何；span/flex 仍按 CSS 布局规则计算最终宽度。
- `ref<GridRef>` 暴露 `nativeElement: HTMLElement | null`，指向实际 div；卸载后清空。Row/Col 自身不增加键盘操作或焦点，原生子控件保持自身行为。`span=0` 隐藏已聚焦内容时浏览器会正常移走焦点。

### Provider

`ConfigProvider :components="{ row: rowConfig, col: colConfig }"`：RowConfig、ColConfig 均支持 `className?: string` 与 `style?: CSSProperties`。当前配置、方向及前缀的出现、替换和移除实时生效。Provider direction 作为原生 dir 的默认值；根的显式 `dir` 或 CSS direction 可覆盖它。嵌套 Provider 与独立实例互不改写配置。

### 断点与 Hook

| 断点 | Col 静态样式范围 | useBreakpoint / Row 响应式值的命中范围 |
| --- | --- | --- |
| xs | 基础样式；直到较大断点显式覆盖 | ≤575px |
| sm | ≥576px | ≥576px |
| md | ≥768px | ≥768px |
| lg | ≥992px | ≥992px |
| xl | ≥1200px | ≥1200px |
| xxl | ≥1600px | ≥1600px |
| xxxl | ≥1920px | ≥1920px |

Col 的各档类同时输出，CSS 按从小到大覆盖；对象中的 0 可清除较小档的偏移/顺序，移除整档时恢复下面仍有效的档。Row 的 justify/align/gutter 按当前命中的断点从大到小查找第一个已配置值；没有匹配值时不设置相应值。例如仅配置 `{ xs: 8, md: 24 }` 的 gutter，在 576–767px 没有命中项。

`useBreakpoint(refreshOnChange?, defaultScreens?)` 返回 `Ref<Screens | null>`。refreshOnChange 接受布尔值或布尔 getter；false 保留上次发布值但缓存媒体变化，getter 恢复 true 时立即发布最新视口。动态开关请传 `() => enabled.value`。相同媒体查询集合共享监听器，不同配置独立观察；配置替换会切换监听器，最后一个订阅者卸载后释放。

SSR 保留 defaultScreens，不访问浏览器。Row 首帧响应式 justify/align 无命中；gutter 在无视口信息时使用最大已定义档，挂载后校正到实际视口。服务端与水合首帧保持确定性，挂载校正可能改变布局。

## Theme 与样式边界

Row/Col 无组件 Token；24 栏是几何常量。字体消费当前全局 fontFamily/fontSize 变量；gutter、flex、逻辑偏移使用响应式几何。Row 负半 margin、Col 正半 padding 合成水平间距，纵向使用 row-gap。基础及响应式 flex 在 nowrap 行中允许收缩（min-width: 0），原生 style 可覆盖。

Col 的静态 CSS 媒体查询固定为表中默认值。运行时 screen Token 覆盖影响 useBreakpoint/Row 的 JavaScript 断点，不重写 Col 的静态媒体查询；需一致时保留默认断点或由应用提供定制静态样式。完整修正与验证边界见 [Grid 迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/grid-contracts.md)。


## 基础栅格 (basic)

从堆叠到水平排列。使用单一的一组 `Row` 和 `Col` 栅格组件，就可以创建一个基本的栅格系统，所有列（Col）必须放在 `Row` 内。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { Col, Row } from '@apollo-design/ui';
</script>

<template>
  <div class="grid-demo">
  <Row>
    <Col :span="24"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-24</div></Col>
  </Row>
  <Row>
    <Col :span="12"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-12</div></Col>
    <Col :span="12"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-12</div></Col>
  </Row>
  <Row>
    <Col :span="8"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-8</div></Col>
    <Col :span="8"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-8</div></Col>
    <Col :span="8"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-8</div></Col>
  </Row>
  <Row>
    <Col :span="6"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-6</div></Col>
    <Col :span="6"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-6</div></Col>
    <Col :span="6"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-6</div></Col>
    <Col :span="6"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-6</div></Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## 区块间隔 (gutter)

`gutter` 支持零、分数、CSS 长度和 `[水平, 纵向]`。两个轴都可以独立配置断点。示例色块使用主题背景和文字变量，保持明暗主题中的可读性。

Both axes accept responsive maps, including zero and fractional spacing.

### gutter.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 gutter demo
import { Col, Row } from '@apollo-design/ui';
</script>

<template>
  <div class="grid-demo">
  <Row :gutter="[10.5, 7.5]">
    <Col v-for="i in 6" :key="i" :span="6"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-6</div></Col>
  </Row>
  <Row :gutter="16">
    <Col v-for="i in 4" :key="i" :span="8"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-8</div></Col>
  </Row>
  <Row :gutter="[{ xs: 8, md: 24 }, { xs: 8, md: 16 }]">
    <Col v-for="i in 4" :key="i" :span="8"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-8</div></Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; padding-inline: 12px; box-sizing: border-box; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## 左右偏移 (offset)

使用 `offset` 可以将列向右侧偏移。

### offset.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 offset demo
import { Col, Row } from '@apollo-design/ui';
</script>

<template>
  <div class="grid-demo">
  <Row>
    <Col :span="8"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-8</div></Col>
    <Col :span="8" :offset="8"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-8</div></Col>
  </Row>
  <Row>
    <Col :span="6" :offset="6"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-6</div></Col>
    <Col :span="6" :offset="6"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-6</div></Col>
  </Row>
  <Row>
    <Col :span="12" :offset="6"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-12</div></Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## 栅格排序 (sort)

列排序。使用 `push`（右移）和 `pull`（左移）改变列的顺序。

### sort.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 sort demo（push/pull）
import { Col, Row } from '@apollo-design/ui';
</script>

<template>
  <div class="grid-demo">
  <Row>
    <Col :span="18" :push="6"><div style="min-height: 30px; height: 100%; box-sizing: border-box; padding: 4px; overflow-wrap: anywhere; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-min-height: 30px; height: 100%; box-sizing: border-box; padding: 4px; overflow-wrap: anywhere; text-align: center; color: var(--apollo-color-text)">col-18 col-push-6</div></Col>
    <Col :span="6" :pull="18"><div style="min-height: 30px; height: 100%; box-sizing: border-box; padding: 4px; overflow-wrap: anywhere; background: var(--apollo-color-primary-bg-hover); border-radius: 4px; line-min-height: 30px; height: 100%; box-sizing: border-box; padding: 4px; overflow-wrap: anywhere; text-align: center; color: var(--apollo-color-text)">col-6 col-pull-18</div></Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## 排版 (flex)

子元素水平对齐方式：`justify` 取 `start` / `center` / `end` / `space-between` / `space-around` / `space-evenly`。

### flex.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 flex demo（justify 排版）
import { Col, Row } from '@apollo-design/ui';

const justifies = [
  'start',
  'center',
  'end',
  'space-between',
  'space-around',
  'space-evenly',
] as const;
</script>

<template>
  <div class="grid-demo">
  <Row v-for="j in justifies" :key="j" :justify="j">
    <Col :span="4"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-4</div></Col>
    <Col :span="4"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-4</div></Col>
    <Col :span="4"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-4</div></Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## 对齐 (flex-align)

子元素垂直对齐方式：`align` 取 `top` / `middle` / `bottom` / `stretch`。`stretch` 拉伸列的交叉轴尺寸；列内具有固定高度的内容仍保留自己的高度。

`stretch` explicitly stretches the column box, while fixed-height children keep their own size.

### flex-align.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 flex-align demo
import { Col, Row } from '@apollo-design/ui';

const aligns = ['top', 'middle', 'bottom', 'stretch'] as const;
</script>

<template>
  <div class="grid-demo">
  <Row v-for="a in aligns" :key="a" :align="a" style="height: 80px; background: var(--apollo-color-fill-alter)">
    <Col :span="4"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-4</div></Col>
    <Col :span="4"><div style="height: 60px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 60px; text-align: center; color: var(--apollo-color-text)">col-4</div></Col>
    <Col :span="4"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">col-4</div></Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## 排序 (flex-order)

通过 `order` 改变元素的排序。

### flex-order.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 flex-order demo
import { Col, Row } from '@apollo-design/ui';

const cols = [
  { key: '1', order: 3 },
  { key: '2', order: 2 },
  { key: '3', order: 1 },
];
</script>

<template>
  <div class="grid-demo">
  <Row>
    <Col v-for="c in cols" :key="c.key" :span="6" :order="c.order">
      <div style="min-height: 30px; height: 100%; box-sizing: border-box; padding: 4px; overflow-wrap: anywhere; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-min-height: 30px; height: 100%; box-sizing: border-box; padding: 4px; overflow-wrap: anywhere; text-align: center; color: var(--apollo-color-text)">{{ c.key }} col-order-{{ c.order }}</div>
    </Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## Flex 填充 (flex-stretch)

`Col` 配合 `flex` 样式实现内容填充。

### flex-stretch.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 flex-stretch demo（百分比列 + 内容撑满）
import { Col, Row } from '@apollo-design/ui';

const contents = [
  { key: '1', percent: '33.33%' },
  { key: '2', percent: '66.67%' },
  { key: '3', percent: '50%' },
];
</script>

<template>
  <div class="grid-demo">
  <Row style="height: 120px">
    <Col v-for="c in contents" :key="c.key" :span="8" :style="{ display: 'flex', flexDirection: 'column' }">
      <div :style="{ background: 'var(--apollo-color-primary-bg)', borderRadius: '4px', color: 'var(--apollo-color-text)', textAlign: 'center', height: c.percent }">
        {{ c.percent }}
      </div>
    </Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## 响应式布局 (responsive)

`xs` … `xxxl` 预设六个响应式尺寸（参照 Bootstrap 的 ≤576 / ≥576 / ≥768 / ≥992 / ≥1200 / ≥1600 / ≥1920），也可传对象配置 span/offset 等。

### responsive.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 responsive demo
import { Col, Row } from '@apollo-design/ui';

const cols = [
  { key: '1', xs: 2, md: 4, xl: 6, xxl: 8 },
  { key: '2', xs: 20, md: 8, xl: 12, xxl: 16 },
];
</script>

<template>
  <div class="grid-demo">
  <Row>
    <Col v-for="c in cols" :key="c.key" :xs="c.xs" :md="c.md" :xl="c.xl" :xxl="c.xxl">
      <div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Col</div>
    </Col>
  </Row>
  <Row>
    <Col :xs="{ span: 5, offset: 1 }" :lg="{ span: 6, offset: 2 }"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Col</div></Col>
    <Col :xs="{ span: 11, offset: 1 }" :lg="{ span: 6, offset: 2 }"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Col</div></Col>
    <Col :xs="{ span: 5, offset: 1 }" :lg="{ span: 6, offset: 2 }"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Col</div></Col>
  </Row>
  <Row>
    <Col :xs="{ span: 11, offset: 1 }" :lg="{ span: 6, offset: 2 }"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Col</div></Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## Flex 响应式布局 (responsive-flex)

`Col` 的 `flex` 与 `Row` 的 `gutter` 均支持响应式对象写法。

### responsive-flex.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 responsive-flex demo（gutter 响应式对象 + Col 响应式 flex）
import { Col, Row } from '@apollo-design/ui';
</script>

<template>
  <div class="grid-demo">
  <Row :gutter="[{ xs: 8, sm: 16, md: 24 }, 16]">
    <Col :xs="{ flex: '100%' }" :sm="{ flex: '50%' }" :md="{ flex: '33.33%' }" :lg="{ flex: '25%' }">
      <div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Flex col</div>
    </Col>
    <Col :xs="{ flex: '100%' }" :sm="{ flex: '50%' }" :md="{ flex: '33.33%' }" :lg="{ flex: '25%' }">
      <div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Flex col</div>
    </Col>
    <Col :xs="{ flex: '100%' }" :sm="{ flex: '50%' }" :md="{ flex: '33.33%' }" :lg="{ flex: '25%' }">
      <div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Flex col</div>
    </Col>
    <Col :xs="{ flex: '100%' }" :sm="{ flex: '50%' }" :md="{ flex: '33.33%' }" :lg="{ flex: '25%' }">
      <div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Flex col</div>
    </Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; padding-inline: 12px; box-sizing: border-box; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## 其他属性的响应式 (responsive-more)

`span` / `offset` 等属性均支持响应式对象写法。

### responsive-more.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 responsive-more demo（span/offset 响应式对象）
import { Col, Row } from '@apollo-design/ui';
</script>

<template>
  <div class="grid-demo">
  <Row>
    <Col :xs="{ span: 20, offset: 2 }" :lg="{ span: 8, offset: 4 }"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Col</div></Col>
    <Col :xs="{ span: 2, offset: 0 }" :lg="{ span: 6, offset: 2 }"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Col</div></Col>
  </Row>
  <Row>
    <Col :xs="{ span: 22, offset: 1 }" :lg="{ span: 10, offset: 2 }"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Col</div></Col>
  </Row>
  <Row>
    <Col :xs="{ span: 10, offset: 1 }" :lg="{ span: 8, offset: 4 }"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Col</div></Col>
    <Col :xs="{ span: 10, offset: 2 }" :lg="{ span: 8, offset: 2 }"><div style="height: 30px; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 30px; text-align: center; color: var(--apollo-color-text)">Col</div></Col>
  </Row>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## 栅格配置器 (playground)

使用三个 Apollo Slider 控件配置水平间距、纵向间距和列数。水平间距包含 `0` / `10.5px`，纵向包含 `0` / `7.5px`；可用方向键、Home、End 调整。

Apollo Sliders demonstrate independent axes, zero/fractional gutters and keyboard input.

### playground.vue

```vue
<script setup lang="ts">
// 使用 Slider 演示零/分数/整像素的独立双轴 gutter。

import { Col, Row, Slider } from '@apollo-design/ui';
import { ref } from 'vue';

const gutterKey = ref(3);
const verticalGutterKey = ref(2);
const colCountKey = ref(3);

const gutters = [0, 8, 10.5, 16, 24];
const vgutters = [0, 7.5, 16, 24];
const colCounts = [2, 3, 4, 6, 8, 12];
</script>

<template>
  <div class="grid-demo">
  <Row :gutter="[gutters[gutterKey] ?? 0, vgutters[verticalGutterKey] ?? 0]">
    <Col v-for="i in colCounts[colCountKey]" :key="i" :span="24 / (colCounts[colCountKey] ?? 1)">
      <div style="min-height: 30px; height: 100%; box-sizing: border-box; padding: 4px; overflow-wrap: anywhere; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 22px; text-align: center; color: var(--apollo-color-text)">col-{{ 24 / (colCounts[colCountKey] ?? 1) }}</div>
    </Col>
  </Row>
  <Row :gutter="[gutters[gutterKey] ?? 0, vgutters[verticalGutterKey] ?? 0]">
    <Col v-for="i in colCounts[colCountKey]" :key="i" :span="24 / (colCounts[colCountKey] ?? 1)">
      <div style="min-height: 30px; height: 100%; box-sizing: border-box; padding: 4px; overflow-wrap: anywhere; background: var(--grid-demo-cell-bg, var(--apollo-color-primary-bg)); border-radius: 4px; line-height: 22px; text-align: center; color: var(--apollo-color-text)">col-{{ 24 / (colCounts[colCountKey] ?? 1) }}</div>
    </Col>
  </Row>
  <div style="display: grid; gap: 12px">
    <div>Horizontal gutter: {{ gutters[gutterKey] }}px<Slider v-model:value="gutterKey" aria-label="horizontal gutter" :min="0" :max="gutters.length - 1" /></div>
    <div>Vertical gutter: {{ vgutters[verticalGutterKey] }}px<Slider v-model:value="verticalGutterKey" aria-label="vertical gutter" :min="0" :max="vgutters.length - 1" /></div>
    <div>Column count: {{ colCounts[colCountKey] }}<Slider v-model:value="colCountKey" aria-label="col count" :min="0" :max="colCounts.length - 1" /></div>
  </div>
  </div>
</template>

<style scoped>
.grid-demo { display: grid; gap: 16px; min-width: 0; padding-inline: 12px; box-sizing: border-box; }
.grid-demo :deep(.apollo-col:nth-child(even)) { --grid-demo-cell-bg: var(--apollo-color-primary-bg-hover); }
</style>
```

## useBreakpoint Hook (useBreakpoint)

`useBreakpoint` 返回各断点的命中状态（基于 `window.matchMedia` 订阅）。

### useBreakpoint.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 useBreakpoint demo
import { useBreakpoint } from '@apollo-design/ui';

const screens = useBreakpoint();
const items = ['xs', 'sm', 'md', 'lg', 'xl', 'xxl', 'xxxl'] as const;
</script>

<template>
  <div>
    当前命中的断点：
    <ul>
      <li v-for="item in items" :key="item">{{ item }}: {{ screens?.[item] ? 'true' : 'false' }}</li>
    </ul>
  </div>
</template>
```

---

# Image

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/image


可预览的图片。预览浮层走 portal，支持缩放 / 旋转 / 翻转 / 组内切换。

## 何时使用

- 需要展示图片，并让用户点击查看大图。
- 一组图片需要统一预览、可左右切换（`Image.PreviewGroup`）。
- 图片加载中/失败时需要占位与兜底（`placeholder` / `fallback`）。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/image/demo)（18 个原生示例）：basic / component-token /
controlled-preview / cover-placement / fallback / image-render / nested /
placeholder / preview-group / preview-group-top-progress / preview-group-visible /
preview-img-info / preview-mask / preview-src / style-class / transform-events /
popup-provider / preview-close。

## API

### Image · Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | 完整根前缀；响应当前prop，移除覆盖后回到当前ConfigProvider命名空间 | `string` | `apollo-image` |
| src | 图片地址 | `string` | — |
| width / height | 宽高。数字会归一化成 `px`（见「设计说明」） | `number \| string` | — |
| alt | 图片替代文本；非空时用作预览触发器及弹层的默认名称。省略时img使用空alt，触发器/弹层保留通用名称 | `string` | `''` |
| fallback | 加载失败时的兜底图 | `string` | — |
| placeholder | 占位内容；`{ progress: true \| { percent, render } }` 时渲染进度层 | `VNodeChild \| { progress }` | — |
| preview | `false` 关闭预览；对象形态见下表 | `boolean \| PreviewConfig` | `true` |
| open | 顶层受控开合，可用 `v-model:open` | `boolean` | — |
| defaultOpen | 非控初值，后续变更不重置状态 | `boolean` | `false` |
| class / style | 根元素原生attrs；style支持Vue字符串/对象/数组，优先于 `styles.root`，不复制到img；图片样式用 `styles.image` | `string \| array \| object` / `StyleValue` | — |
| wrapperStyle | ⚠️ 已废弃，请用 `styles.root` | `CSSProperties` | — |
| classNames / styles | 语义化类名/样式，见「语义化槽位」 | — | — |
| crossOrigin / decoding / loading / referrerPolicy / sizes / srcSet / useMap / draggable | 透传给 `<img>` 的原生属性 | — | — |

进度/纯占位分支的原生attrs落在现有Progress根，合并Image根与placeholder.progress语义，style仍优先。id/data及名称/描述ARIA保持当前值；role、范围和busy状态由进度控制。移除显式aria-label恢复百分比默认名称。根click通知一次且不打开预览，img error不改挂到占位根。详见 [原生样式修正](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-native-styles.md)。

### Image · 插槽

| 名称 | 说明 | 参数 |
|---|---|---|
| imageRender | 自定义缩略图区域；空槽抑制默认img | 单对象 `ImageRenderInfo`，见下文 |
| previewImage | 自定义预览大图区域 | 单对象 `PreviewImageInfo` |
| previewActions | 自定义预览工具栏 | 单对象 `PreviewActionsInfo` |
| previewCloseIcon | 自定义关闭图标；空槽也优先，按钮名称独立保留 | 无参数 |

`originNode` 是带原始ref、加载/错误处理、原生属性与样式的真实VNode，建议用 `<component :is="originNode" />` 渲染。`src` 是当前原图的原始src属性（含fallback，缺省undefined）；alt/width/height来自当前props，title来自字符串原生attr，classNames.image是已合并的语义image类名。槽存在则使用其内容（含有意为空），移除恢复默认img；同一结构下的原图和稳定富节点保持身份。Progress/纯占位提前分支不调用此槽。

`ImageSlots` / `ImageRenderInfo` 已从组件和包根导出。顶层函数prop直接移除，无兼容层或弃用期；详见 [迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-render-slot.md)。预览扩展使用下方独立命名的作用域槽。

### 预览槽作用域

Image与PreviewGroup均支持previewImage/previewActions/previewCloseIcon；Group另支持previewCount。所有槽只在实际预览内容渲染时读取当前函数，空槽抑制默认内容，移除槽恢复默认；闭合/SSR及Progress提前分支不急求值。Group内只有Group负责预览扩展，子Image的imageRender仍只作用于缩略图。

| 类型 | 字段 |
|---|---|
| PreviewImageInfo | originNode（真实img VNode）、src（原始src，含fallback，可能undefined）、alt、transform、current、total |
| PreviewActionsInfo | originNode（默认工具栏VNode）、icons、actions、transform、image（src/alt）、current、total、disabled（zoomIn/zoomOut） |
| PreviewCountInfo | originNode（默认计数VNode）、current、total；仅Group |

current为零基索引，与Group模型相同，显示序号时加1；单图current=0/total=1。transform为当前六字段快照。actions提供flipX/flipY/rotateLeft/rotateRight/zoomIn/zoomOut/reset/close零参回调，与默认控件共用变换与关闭请求；disabled给出当前缩放按钮状态。输入、textarea、select和contenteditable内的方向键保留编辑行为，Esc仍可请求关闭，子控件preventDefault优先。

上述类型、PreviewActions与PreviewGroupSlots均由根入口导出。通过 `<component :is="info.originNode" />` 保留原图的ref/手势或默认工具栏；迁移旧preview内renderer见 [预览槽迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-preview-slots.md)。

### Image · PreviewConfig（`preview` 的对象形态）

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| src | 预览用大图（默认取 `src`） | `string` | — |
| afterOpenChange | 开合动画结束后 | `(open) => void` | — |
| cover | 缩略图封面；`false` 隐藏，null或省略使用默认内容；配置对象可只指定placement | `VNodeChild \| { placement?: 'center' \| 'top' \| 'bottom', coverNode?: VNodeChild }` | — |
| mask | 预览遮罩外观；false隐藏遮罩；对象支持blur/className/style，语义styles.popup.mask优先 | `boolean \| { blur?: boolean, className?: string, style?: Record<string, string \| number> }` | `true` |
| maskClosable | 点遮罩关闭 | `boolean` | `true` |
| closable | 显示关闭按钮 | `boolean` | `true` |
| closeIcon | 自定义关闭图标 | `VNodeChild` | — |
| movable | 可拖拽 | `boolean` | `true` |
| minScale / maxScale / scaleStep | 缩放边界与步长 | `number` | `1` / `50` / `0.5` |
| zIndex | 浮层层级 | `number` | `1080`（`zIndexPopupBase + 80`） |
| getContainer | 当前浮层挂载容器；未指定时使用ConfigProvider.getPopupContainer，再回到body | `() => HTMLElement` | `document.body` |
| icons | 图标槽（rotateLeft/rotateRight/zoomIn/zoomOut/close/left/right/flipX/flipY） | `PreviewIcons` | 内置图标 |
| rootClassName | 浮层根附加类；语义入口为classNames.popup.root | `string` | — |
| maskClassName | 浮层遮罩附加类；语义入口为classNames.popup.mask | `string` | — |

关闭图标优先级为当前 `#previewCloseIcon` → 显式 `preview.closeIcon`（含 null/false/0）→ `preview.icons.close` → 默认图标。`closable=false` 只隐藏关闭按钮且不求值图标槽；Esc、maskClosable 与工具栏 close 动作仍各自生效。显示/隐藏和内容替换保留预览身份、编辑器与变换，按钮始终有独立名称。见 [关闭控件回归](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-preview-close-remediation.md)。

Image/Group 每次缩放、滚轮、双击及非复位变换读取当前 minScale/maxScale；替换或移除配置会作用于下一次操作。更改配置本身保留现有比例与预览身份，不发 transform。比例达到或超过当前上限时，放大按钮与 previewActions.disabled.zoomIn 同时禁用；复位/关闭仍回到比例 1。见 [边界回归](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-scale-bounds-remediation.md)。

scaleStep是比例增量：放大乘以1+step，缩小除以1+step；默认0.5使1放大为1.5，当前值也用于滚轮及从1开始的双击放大。step/min/max须为有限正数，无效值使用默认值；max小于min时按min处理。容器、资源加载、分组类型和步长集中修正见 [本轮迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-contracts.md)；forceRender/destroyOnClose已从类型移除。

加载状态只由实际img的原生事件和缓存完成状态驱动，不额外构造Image或发起校验请求。fallback启用时移除失败的srcSet/sizes，避免候选图覆盖兜底；src/srcSet/sizes更新后重新尝试当前资源。拖拽仅接受主键，关闭、禁用movable、失去主键、窗口失焦及卸载均释放原窗口监听器。

### Image · Events

| 名称 | 说明 |
|---|---|
| click | 原MouseEvent；可预览时内部打开请求后通知，支持Vue修饰符和监听器数组 |
| error | 原img的Event；占位根不接收图片error，error.once正确归于组件事件 |
| keydown | 原KeyboardEvent；监听器先于内置Enter/Space，preventDefault可阻止内置键盘动作 |
| openChange | 交互请求 `(nextOpen: boolean, prevOpen: boolean)`，写入前捕获前态 |
| update:open | 顶层 `v-model:open` 的boolean请求；父prop变化不回发 |
| transform | 当前变换的完整 `TransformInfo` 快照（rotate/scale/flipX/flipY/x/y）；接受关闭后也通知复位，拒绝关闭不复位 |

preview=false保留原生role/tabindex/aria-label；普通可预览根拥有button/0。imageRender插槽或VNode封面使用group根，非空图片内容提供独立可见的原生预览按钮；originNode保持普通img，可放入调用者的原生控件。输入、按钮、label、可编辑内容及已取消事件不触发预览，无需.stop；图片及非交互封面可点击预览，说明文字可选择。富内容根自然展开，height仍作用于图片，显式root样式优先。按钮名称为“Preview image: 名称”，名称优先显式aria-label，其次alt；普通根的默认名称保持不变。Progress只通知click/keydown，不打开潜在预览。以 `@click` / `@error` / `@keydown` 绑定；h()/ImageProps中的onXxx是Vue监听器注册。详见 [集中迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-contracts.md)。

预览锁定所属文档body滚动与焦点直到退场结束，mask=false仍为模态预览；多实例分别释放，关闭返回实际触发器。Escape使用所属窗口最上层及IME保护，子控件preventDefault优先；分组方向键仅在非编辑目标且无修饰/组合输入时切换。系统reduced-motion、主题motion=false或当前过渡零时长不等待500ms兜底；偏好/主题动态变化保留现有预览内容。

imageRender完全替换originNode时，非空内容保留独立可见的原生预览按钮，不把表单包成按钮；空槽不补按钮。触发器在打开期间被替换时，关闭后优先归还仍有效的保存焦点，必要时回到当前可用预览入口。

开合只有顶层Vue状态入口。open省略使用内态，移除控制接续最后同步值；交互先openChange再update:open，父级可以拒绝请求。旧preview状态字段直接移除，afterOpenChange等业务配置保持，见 [模型迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-open-model.md)。失效的preview.onTransform直接迁到顶层 `@transform`，类型可从根入口导入；支持监听器数组、替换与 `.once`，不混入根DOM同名事件，见 [变换事件迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-transform-event.md)。

预览打开后焦点进入弹层，Tab/Shift+Tab在其中循环，Esc请求关闭。受控父级拒绝关闭时保留焦点；关闭动画结束或整个预览卸载后归还原触发器。关闭与组内切换按钮自带可访问名称，自定义装饰图标不会移除名称。

### Image.PreviewGroup · Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| items | 图片列表（首选）；原生图片属性加src/width/height/fallback，可附带业务元数据 | `Array<string \| PreviewGroupItem>` | — |
| preview | 预览行为配置；不含Image专属src/cover，分别配置items/子Image | `boolean \| GroupPreviewConfig` | `true` |
| open | 顶层受控开合，可用 `v-model:open` | `boolean` | — |
| defaultOpen | 非控初值，后续变更不重置状态 | `boolean` | `false` |
| current | 受控当前索引 | `number` | — |
| defaultCurrent | 非受控初始索引 | `number` | `0` |
| previewPrefixCls | 完整预览前缀；当前prop优先，移除后使用当前Provider派生值 | `string` | `${prefixCls}-preview` |
| classNames / styles | 分组实际root及共享popup的语义配置；子Image语义在子组件或Provider配置 | `PreviewGroupSemanticType` 对应字段 | — |

移除current控制后接续最后同步索引；非受控列表缩短时归一到可用范围。空列表不挂载空弹层；preview=false或空列表的子Image不提供无效预览按钮语义。items和注册数据均透传尺寸及fallback，只将原生图片属性传给实际img。

### Image.PreviewGroup · 插槽与 Events

| 名称 | 说明 |
|---|---|
| default | 子 `Image`（`items` 未传时按注册顺序收集） |
| previewImage / previewActions | 同Image原生预览槽 |
| previewCloseIcon | 同Image无参数关闭图标槽；组内只消费Group自己的槽 |
| previewCount | 原生计数槽，单对象PreviewCountInfo，current为零基索引 |
| openChange / update:open | 同Image开合请求/模型通知，可用 `v-model:open` |
| change | 索引请求 `(current: number, prevCurrent: number)` |
| update:current | change之后的数字模型请求，可用 `v-model:current` |
| transform | 同Image变换快照；组内子Image不重复通知 |

### 语义化槽位

Image通过 `ConfigProvider.components.image.classNames/styles` 接收静态对象语义配置；Image与PreviewGroup的共享预览均读取其中的popup组。字段、image或整个components map替换、晚出现和移除都会读取当前值，原图、富内容和已打开预览保持同结构节点与状态。普通图/Progress证据见 [报告](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-provider-remediation.md)，弹层六个节点的当前配置见 [预览配置报告](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-popup-provider-remediation.md)。

`classNames` / `styles` 的槽位（`placeholder` 与 `popup` 是**嵌套组**）：

```
root / image / cover
placeholder.progress: root / content / rail / indicator
popup: root / mask / body / footer / actions / close
```

Provider/局部classNames通过嵌套schema拼接，再追加现有预览类名配置。styles.popup按字段浅合并：局部popup.root替换Provider的整个root样式对象，其他未覆盖字段保留。原生class/style留在Image或Group实际根，不复制到弹层；Image根style仍优先于styles.root。本批不改变共享合并规则或增加函数式配置。

Group导航图标读取当前ConfigProvider.direction，ltr/rtl切换时先合并默认与自定义图标再镜像。单侧自定义保留另一侧默认图标；显式null保持为空。当前icons对象替换/移除会更新，已打开的图片、变换和编辑器保持；Previous/Next按钮继续请求相邻索引并保留名称，见 [方向回归](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-provider-direction-remediation.md)。

### 静态属性 / 具名导出

| 名称 | 说明 |
|---|---|
| `Image.PreviewGroup` | 预览分组。同时具名导出 `ImagePreviewGroup` |
| `genImageStyle(prefixCls?)` | 产出该组件的完整 CSS（自定义前缀时用） |
| `genImageTokenDecls()` | 组件变量声明块（对拍 antd 的 `-css-var` 块） |
| `prepareImageComponentToken(seed)` | Component Token 派生（类型 `ImageComponentToken` 同名导出） |

### 类型导出

`ImageProps`、`PreviewConfig`、`PreviewGroupProps`、`GroupPreviewConfig`、`PreviewIcons`、
`PlaceholderType`、`ImageProgressConfig`、`ImageStatus`、`CoverPlacement`、`MaskType`、
`TransformInfo`、`ImageSemanticType`、`PreviewGroupSemanticType`、`PreviewGroupItem`、`ProgressClassNames`、`ProgressStyles`。Image.PreviewGroup与具名ImagePreviewGroup使用相同的完整声明类型。

## Theme（Component Token）

7 个（CSS 变量 `--apollo-image-*`）：`zIndexPopup`(`zIndexPopupBase + 80` = 1080) /
`previewOperationColor`(`colorTextLightSolid` @0.65) / `previewOperationHoverColor`(@0.85) /
`previewOperationColorDisabled`(@0.25) / `previewOperationSize`(`fontSizeIcon × 1.5` = 18px) /
`progressAnimationDuration`(`3s`)；`imagePreviewSwitchSize`(= `controlHeightLG`，默认40px，对应 `--apollo-image-preview-switch-size`)，控制分组切换按钮实际宽高。

通过 `ConfigProvider.theme.components.Image` 覆盖全部7个Token。缩略图、Progress和body中的预览从同一个Vue主题上下文读取当前alias/组件变量；支持外层ThemeProvider、嵌套继承、暗色/紧凑算法、配置替换和移除。未配置主题时由静态CSS负责默认值；Image原生style和popup语义style可覆盖对应变量。层级优先级为preview.zIndex、styles.popup.root.zIndex、父浮层层级、组件变量。见实际component-token示例及 [统一证据](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-contract-audit.md)。

Group 默认计数使用 `colorBgSpotlight` 背景，文字继续继承 footer 的操作颜色；在亮色页面及关闭遮罩时仍有独立的对比背景。该背景只作用于默认计数节点（也包括 `previewCount.originNode`），自定义计数槽保留自身样式。见 [对比度回归](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-counter-contrast-remediation.md)。

## 设计说明

### 数字型 `width` / `height` 会归一化成 `px`

Vue 的 `style` **不会**给数字自动补 `px`（那是 React 的行为），裸数字会被静默丢弃。
所以组件内部统一走 `toCssSize()`：根元素与 `<img>` 的 `style`、`Progress` 的宽高都转成字符串。
漏了这一步不会报错 —— `<img>` 会退回 CSS 的 `height:auto`，按原始比例撑高，
**看起来「有图」但尺寸错了**，只有 L6 像素比对能抓到。

### 组件变量声明块挂在两个根上

静态默认声明同时挂在 `.apollo-image` 与 `.apollo-image-preview`。配置了主题时，两者在自己的实际根写当前CSS变量；Vue的provide/inject跨Teleport保持同一上下文，所以预览不依赖源DOM的变量继承。不生成组件样式表或向全局写入局部主题。

### 预览浮层走 portal

`Image` 的可 SSR 部分是根 `div` + `<img>` + 占位 + 封面；预览浮层经
`@apollo-design/portal` 挂到 `body`（`getContainer` 可改），因此 **SSR 产物里看不到它**。
`preview=false` 时连浮层组件都不挂载。

### 样式引入

```ts
import '@apollo-design/theme/tokens.css'; // 主题变量，必须先引
import '@apollo-design/ui/image/style.css';    // 按需
// 或
import '@apollo-design/ui/style.css';          // 汇总
```

默认发布CSS使用apollo命名空间。`ConfigProvider.prefixCls="my-app"` 对应Image根 `my-app-image` 和预览 `my-app-image-preview`；在应用构建中用 `genImageStyle('my-app')` 预生成并加载对应CSS。Image.prefixCls与Group.previewPrefixCls接受完整前缀。动态更新改变DOM命名，所用命名空间的CSS需预先加载，组件运行时不生成样式。已打开预览和同结构富节点保留状态，见 [前缀证据](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-prefix-remediation.md)；D04整体策略继续独立追踪。

## FAQ

**为什么预览浮层的 `z-index` 是 1080？**

`zIndexPopup = zIndexPopupBase(1000) + 80`，与 antd 逐字一致；`preview.zIndex` 可覆盖。

**`Image.PreviewGroup` 的 `items` 和默认插槽能同时用吗？**

`items` 优先。未传 `items` 时按子 `Image` 的注册顺序收集（注册返回自增 id）。

**组内切换时浮层会重建吗？**

不会。组内只挂**一个** `Preview`，切换时更新 `src` 与 `mousePosition`。

Group通过Vue注册关系维护归属，嵌套组相互隔离，Teleport不会改变图片所属组；显式items优先，移除items后恢复子图注册。打开者被删除后，关闭归还本组仍可用的预览入口，不选择嵌套组或业务控件。删除无控当前项会归一到有效索引，数据更新不回声change/update:current。


## 语义化样式 (style-class)

通过 `classNames` 与 `styles` 自定义图片容器、图片本身与预览遮罩。第一个示例保留自定义遮罩，悬停可见并支持预览。

后面的原生 `class` / `style` 循环使用动态 `StyleValue`：字符串 → 混合数组 → 对象 → 移除。原生 style 只控制实际外根，优先于语义根样式；img 的独立 `styles.image` 不被根样式覆盖。移除时恢复语义根值，富内容的图片、输入草稿和焦点保持。

进度分支也保留根 id、data、可访问名称/描述与样式，同时由组件控制 progressbar 的角色和数值。示例使用本地 data URI，不依赖图片网络请求。

独立的 ConfigProvider 按钮替换整个 `components` map：空配置 → 全新 Image 配置 A → 全新配置 B → 移除。配置使用既有 `ImageSemanticType` 数据对象。root、img、cover 的类名和额外 CSS 变量随配置更新，placeholder.progress 类名也保持当前值。既有浅合并规则下，本地 progress 样式整组覆盖 Provider 同组，因此该组的 Provider 变量不保留。局部语义与原生根样式保持优先，原有样式循环和输入草稿保持独立。

### style-class.vue

```vue
<script setup lang="ts">
// 语义化 classNames / styles：root / image / cover 三个槽位。
import {
  Button,
  ConfigProvider,
  type ConfigProviderProps,
  Image,
  type ImageSemanticType,
} from '@apollo-design/ui';
import { computed, ref, type StyleValue, shallowRef } from 'vue';

const src = `data:image/svg+xml,${encodeURIComponent(
  `<svg xmlns="http://www.w3.org/2000/svg" width="640" height="360" viewBox="0 0 640 360">
    <defs>
      <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
        <stop offset="0" stop-color="#1677ff"/>
        <stop offset="1" stop-color="#eb2f96"/>
      </linearGradient>
    </defs>
    <rect width="640" height="360" fill="url(#g)"/>
    <circle cx="500" cy="96" r="56" fill="rgba(255,255,255,0.28)"/>
    <circle cx="96" cy="280" r="92" fill="rgba(255,255,255,0.14)"/>
    <text x="40" y="320" fill="#ffffff" font-family="sans-serif" font-size="28">
      Apollo Design
    </text>
  </svg>`,
)}`;

const classNames = {
  root: 'demo-image-style-root',
  image: 'demo-image-style-img',
  cover: 'demo-image-style-cover',
};

const styles = {
  root: { borderRadius: '12px', overflow: 'hidden' },
  cover: {
    background: 'rgba(22, 119, 255, 0.4)',
    color: '#ffffff',
    fontSize: '14px',
  },
};

const preview = { cover: '点击预览' };

const phase = ref(0);
const nativeClass = computed(() =>
  phase.value < 3 ? ['native-demo-root', `native-demo-phase-${phase.value}`] : undefined,
);
const nativeStyle = computed<StyleValue>(() => {
  if (phase.value === 0) return 'padding-top:var(--apollo-padding-xs);--native-demo-phase:string';
  if (phase.value === 1)
    return [
      'padding-top:var(--apollo-padding-sm);--native-demo-phase:array',
      { paddingInlineEnd: 'var(--apollo-padding-xs)' },
    ];
  if (phase.value === 2)
    return {
      paddingTop: 'var(--apollo-padding-md)',
      paddingInlineStart: 'var(--apollo-padding-xs)',
      '--native-demo-phase': 'object',
    };
  return undefined;
});
const nativeSemanticStyles = {
  root: { height: 'auto', paddingTop: 'var(--apollo-padding-xxs)', '--semantic-demo-root': 'kept' },
  image: { objectFit: 'cover', paddingTop: 'var(--apollo-padding-xxs)', boxSizing: 'border-box' },
};
const progressSemanticStyles = {
  root: { paddingTop: 'var(--apollo-padding-xxs)', '--semantic-demo-root': 'kept' },
  placeholder: { progress: { root: { paddingTop: 'var(--apollo-padding-xxs)' } } },
};

const providerStage = ref(0);
const providerStateLabels = ['empty', 'A', 'B', 'removed'];
const makeImageProvider = (variant: 'A' | 'B'): ImageSemanticType => {
  const color =
    variant === 'A' ? 'var(--apollo-color-primary-border)' : 'var(--apollo-color-success-border)';
  return {
    classNames: {
      root: `provider-image-root-${variant}`,
      image: `provider-image-img-${variant}`,
      cover: `provider-image-cover-${variant}`,
      placeholder: {
        progress: {
          root: `provider-image-progress-root-${variant}`,
          content: `provider-image-progress-content-${variant}`,
          rail: `provider-image-progress-rail-${variant}`,
          indicator: `provider-image-progress-indicator-${variant}`,
        },
      },
    },
    styles: {
      root: {
        '--provider-image-root': variant,
        outlineColor: color,
        outlineStyle: 'solid',
        outlineWidth: 'var(--apollo-line-width)',
        paddingTop: 'var(--apollo-padding-lg)',
      },
      image: {
        '--provider-image-img': variant,
        outlineColor: color,
        outlineStyle: 'solid',
        outlineWidth: 'var(--apollo-line-width)',
        paddingTop: 'var(--apollo-padding-lg)',
      },
      cover: {
        '--provider-image-cover': variant,
        outlineColor: color,
        outlineStyle: 'solid',
        outlineWidth: 'var(--apollo-line-width)',
      },
      placeholder: {
        progress: {
          root: {
            '--provider-image-progress-root': variant,
            outlineColor: color,
            outlineStyle: 'solid',
            outlineWidth: 'var(--apollo-line-width)',
            paddingTop: 'var(--apollo-padding-lg)',
          },
          content: { '--provider-image-progress-content': variant },
          rail: { '--provider-image-progress-rail': variant },
          indicator: {
            '--provider-image-progress-indicator': variant,
            fontWeight: 'var(--apollo-font-weight-strong)',
          },
        },
      },
    },
  };
};
const imageProviderComponents = shallowRef<NonNullable<ConfigProviderProps['components']>>({});
const cycleImageProvider = () => {
  providerStage.value = (providerStage.value + 1) % 4;
  const variant = providerStage.value === 1 ? 'A' : providerStage.value === 2 ? 'B' : undefined;
  imageProviderComponents.value = variant ? { image: { ...makeImageProvider(variant) } } : {};
};
</script>

<template>
  <ConfigProvider :components="imageProviderComponents">
    <div class="demo-image-style-wrap" data-image-provider-demo>
      <p>
        <Button html-type="button" @mousedown.prevent @click="cycleImageProvider">Cycle image provider configuration</Button>
        <output data-image-provider-state>{{ providerStateLabels[providerStage] }}</output>
      </p>
      <Image
        :width="320"
        :src="src"
        alt="Gradient artwork"
        :preview="preview"
        :class-names="classNames"
        :styles="styles"
      />
      <p class="demo-image-style-hint">悬停查看自定义遮罩，点击打开预览。</p>
      <section data-image-native-style-demo>
        <p><Button html-type="button" @mousedown.prevent @click="phase = (phase + 1) % 4">Cycle native image styles</Button></p>
        <Image data-image-native-style :width="280" :height="160" :src="src" alt="Native image style example" :preview="false"
          :class="nativeClass" :style="nativeStyle" :class-names="{ root: 'semantic-demo-image-root' }" :styles="nativeSemanticStyles">
          <template #imageRender="{ originNode }">
            <figure class="demo-native-image-frame">
              <component :is="originNode" />
              <figcaption>Native style: {{ ['string', 'array', 'object', 'removed'][phase] }}</figcaption>
              <input aria-label="Native image style draft" @click.stop @keydown.stop />
            </figure>
          </template>
        </Image>
        <p id="native-image-style-help">Progress retains the same native root class, style and description.</p>
        <Image id="native-image-progress" data-image-native-progress-style :width="280" :height="100"
          :placeholder="{ progress: { percent: 50 } }" aria-label="Native image loading progress" aria-describedby="native-image-style-help"
          :class="nativeClass" :style="nativeStyle" :class-names="{ root: 'semantic-demo-progress-root', placeholder: { progress: { root: 'semantic-demo-progress-content' } } }" :styles="progressSemanticStyles" />
      </section>
    </div>
  </ConfigProvider>
</template>

<style>
.demo-image-style-wrap {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

.demo-image-style-root {
  border: 1px solid var(--apollo-color-border);
  box-shadow: var(--apollo-box-shadow-tertiary);
}

.demo-image-style-img {
  display: block;
}

.demo-image-style-cover {
  backdrop-filter: blur(2px);
}

.demo-native-image-frame {
  display: flex;
  flex-direction: column;
  gap: var(--apollo-margin-xs);
  margin: 0;
}
.demo-native-image-frame input {
  box-sizing: border-box;
  width: 100%;
}
</style>
```

## basic (basic)

基本用法（点击可预览）。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic.tsx —— ⚠️ 图片用 data URI（外网图片会污染 L6 基线）
import { Image } from '@apollo-design/ui';

const src =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
</script>

<template>
  <Image :width="200" alt="basic" :src="src" />
</template>
```

## component-token (component-token)

通过局部ConfigProvider覆盖全部7个Image Token；预览经Portal挂到body后仍消费源主题。打开单图或分组后，在工具栏切换自定义亮色、暗色紧凑和移除主题，观察图标字号、分组按钮尺寸、层级及进度动效时长。编辑器与当前预览保持；自定义样式仍可覆盖变量。

### component-token.vue

```vue
<script setup lang="ts">
import './thumbnail-groups.css';
import { compactAlgorithm, darkAlgorithm } from '@apollo-design/theme';
import {
  Button,
  ConfigProvider,
  type ConfigProviderThemeConfig,
  Image,
  ImagePreviewGroup,
  Input,
} from '@apollo-design/ui';
import { computed, ref } from 'vue';

const phase = ref(0);
const theme = computed<ConfigProviderThemeConfig | undefined>(() =>
  phase.value === 2
    ? undefined
    : {
        algorithm: phase.value === 1 ? [darkAlgorithm, compactAlgorithm] : undefined,
        token: { colorBgSpotlight: phase.value === 1 ? '#273047' : '#14213d' },
        components: {
          Image: {
            zIndexPopup: phase.value === 1 ? 2100 : 2000,
            previewOperationColor: '#ffffff',
            previewOperationHoverColor: '#fadb14',
            previewOperationColorDisabled: 'rgba(255,255,255,0.5)',
            previewOperationSize: phase.value === 1 ? 27 : 31,
            progressAnimationDuration: phase.value === 1 ? '2s' : '4s',
            imagePreviewSwitchSize: phase.value === 1 ? 64 : 52,
          },
        },
      },
);
const change = () => {
  phase.value = (phase.value + 1) % 3;
};
const src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="240" height="140"><rect width="240" height="140" fill="#38598b"/></svg>')}`;
</script>

<template>
  <section data-image-token-demo>
    <Button html-type="button" @mousedown.prevent @click="change">Cycle component tokens</Button>
    <ConfigProvider :theme="theme">
      <div class="image-token-examples">
        <Image :src="src" alt="Themed single image" :width="160" data-token-image>
          <template #previewActions="info"><component :is="info.originNode" /><div class="image-token-controls"><Button html-type="button" @mousedown.prevent @click="change">Cycle component tokens</Button><output>Phase {{ phase }}</output></div></template>
          <template #previewImage="info"><figure class="image-token-editor"><component :is="info.originNode" /><Input aria-label="Token preview note" /></figure></template>
        </Image>
        <ImagePreviewGroup class="image-demo-thumbnails">
          <Image :src="src" alt="Themed group first" :width="120" data-token-group />
          <Image :src="src" alt="Themed group second" :width="120" />
          <template #previewActions="info"><component :is="info.originNode" /><div class="image-token-controls"><Button html-type="button" @mousedown.prevent @click="change">Cycle component tokens</Button><output>Phase {{ phase }}</output></div></template>
          <template #previewImage="info"><figure class="image-token-editor"><component :is="info.originNode" /><Input aria-label="Token preview note" /></figure></template>
        </ImagePreviewGroup>
        <Image :width="160" :height="100" :placeholder="{ progress: { percent: 65 } }" />
      </div>
    </ConfigProvider>
  </section>
</template>

<style>
.image-token-examples { display: flex; flex-wrap: wrap; align-items: center; gap: var(--apollo-margin); margin-top: var(--apollo-margin-sm); }
.image-token-controls { display: flex; gap: var(--apollo-margin-xs); align-items: center; padding: var(--apollo-padding-xs); color: var(--apollo-color-text-light-solid); background: var(--apollo-color-bg-spotlight); }
.image-token-controls button, .image-token-editor input { color: var(--apollo-color-text); background: var(--apollo-color-bg-container); }
.image-token-editor { display: flex; flex-direction: column; align-items: center; gap: var(--apollo-margin-xs); margin: 0; }
</style>
```

### thumbnail-groups.css

```css
/* Keep grouped thumbnails distinct when the Demo canvas wraps to a narrow width. */
.image-demo-gallery,
.image-demo-thumbnails {
  display: flex;
  flex-wrap: wrap;
  align-items: flex-start;
  gap: 12px;
  min-width: 0;
  max-width: 100%;
}
```

## controlled-preview (controlled-preview)

使用顶层 `v-model:open` 控制预览。父组件按钮直接更新模型；图片点击或预览关闭通过模型同步，`@open-change(next, prev)` 显示组件请求的前后状态。父组件直接赋值不会触发此事件。

另一个按钮按需挂载设置了顶层 `defaultOpen` 的非受控图片，展示初始打开状态；之后由组件管理开关。两种状态用法都不再放入 `preview` 配置对象。

### controlled-preview.vue

```vue
<script setup lang="ts">
import { Button, Image } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const openChanges = ref(0);
const lastOpenChange = ref('none');
const showInitiallyOpen = ref(false);
const defaultOpenChanges = ref(0);
const lastDefaultOpenChange = ref('none');
const src =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';

function onOpenChange(next: boolean, prev: boolean) {
  openChanges.value++;
  lastOpenChange.value = `${prev} → ${next}`;
}

function onDefaultOpenChange(next: boolean, prev: boolean) {
  defaultOpenChanges.value++;
  lastDefaultOpenChange.value = `${prev} → ${next}`;
}
</script>

<template>
  <section data-image-controlled-demo style="display: flex; flex-direction: column; row-gap: 8px; align-items: flex-start">
    <Button html-type="button" aria-haspopup="dialog" :aria-expanded="open" @mousedown.prevent @click="open = !open">
      {{ open ? 'Close controlled image preview' : 'Open controlled image preview' }}
    </Button>
    <Image v-model:open="open" alt="Controlled preview image"
      :width="200"
      :src="src"
      @open-change="onOpenChange"
    />
    <p>Parent open model: <output data-image-controlled-open>{{ open }}</output>; component open changes: <output data-image-controlled-open-changes>{{ openChanges }}</output>; previous → next: <output data-image-controlled-open-transition>{{ lastOpenChange }}</output>.</p>
    <Button html-type="button" :aria-pressed="showInitiallyOpen" @mousedown.prevent @click="showInitiallyOpen = !showInitiallyOpen">
      {{ showInitiallyOpen ? 'Remove initially open image' : 'Show initially open image' }}
    </Button>
    <Image v-if="showInitiallyOpen" data-image-default-open :default-open="true" alt="Initially open preview image"
      :width="200" :src="src" @open-change="onDefaultOpenChange" />
    <p>Uncontrolled open changes: <output data-image-default-open-changes>{{ defaultOpenChanges }}</output>; previous → next: <output data-image-default-open-transition>{{ lastDefaultOpenChange }}</output>.</p>
  </section>
</template>
```

## cover-placement (cover-placement)

`preview.cover.placement` 指定封面（hover 层）位置。

### cover-placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/coverPlacement.tsx
import { Image } from '@apollo-design/ui';
import { h } from 'vue';

const src =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
const placements = ['center', 'top', 'bottom'] as const;
const coverNode = (text: string) => h('span', text);
void coverNode;
</script>

<template>
  <div style="display: flex; gap: 16px">
    <Image alt="demo image"
      v-for="p in placements"
      :key="p"
      :width="96"
      :src="src"
      :preview="{ cover: { placement: p, coverNode: p } }"
    />
  </div>
</template>
```

## transform-events (transform-events)

通过顶层 `@transform="info => ..."` 接收当前旋转、缩放、翻转和位移的 `TransformInfo` 快照；`@transform.once` 使用标准 Vue 单次事件语义。Image 与 PreviewGroup 使用同一事件，组内子 Image 不重复通知。关闭预览会复位变换并通知复位快照；父级拒绝关闭时不复位。

原来未生效的 `preview.onTransform` 直接移除此配置字段，改用顶层事件，没有兼容通道。`TransformInfo` 可从 `@apollo-design/ui` 导入。

打开时可切换默认、窄范围和较高下限。更改边界不会主动发变换通知或重挂预览；下一次缩放、手势或其他非复位变换读取当前边界。当前比例达到或超过上限时，放大按钮及槽的 disabled.zoomIn 均为禁用；移除配置恢复默认边界，复位/关闭仍回到比例 1。

### transform-events.vue

```vue
<script setup lang="ts">
import './thumbnail-groups.css';
import {
  Button,
  Image,
  ImagePreviewGroup,
  type PreviewConfig,
  type TransformInfo,
} from '@apollo-design/ui';
import { computed, ref, shallowRef } from 'vue';

const imageChanges = ref(0);
const groupChanges = ref(0);
const imageOnce = ref(0);
const groupOnce = ref(0);
const last = shallowRef<{ source: string; transform: TransformInfo } | null>(null);
const boundsMode = ref(0);
const preview = computed<PreviewConfig>(() =>
  boundsMode.value === 1
    ? { minScale: 1, maxScale: 1.05 }
    : boundsMode.value === 2
      ? { minScale: 1.15, maxScale: 2 }
      : {},
);
function cycleBounds() {
  boundsMode.value = (boundsMode.value + 1) % 3;
}
const source = (color: string) =>
  `data:image/svg+xml;charset=utf-8,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="180" height="110"><rect width="180" height="110" fill="${color}"/></svg>`)}`;
const first = source('#38598b');
const second = source('#297373');
function recordImage(info: TransformInfo) {
  imageChanges.value++;
  last.value = { source: 'Image', transform: info };
}
function recordGroup(info: TransformInfo) {
  groupChanges.value++;
  last.value = { source: 'PreviewGroup', transform: info };
}
</script>

<template>
  <section data-image-transform-demo>
    <p>Open a preview and rotate, flip or zoom its image. Closing resets the transform and emits that snapshot.</p>
    <Button html-type="button" @mousedown.prevent @click="cycleBounds">Cycle preview bounds</Button>
    <p>Current bounds: <output data-transform-demo-bounds>{{ boundsMode === 1 ? '1–1.05' : boundsMode === 2 ? '1.15–2' : 'default' }}</output>. A bound change applies on the next transform action.</p>
    <div class="image-demo-gallery">
<Image :src="first" alt="Transform event image" :width="180" :height="110"
      :preview="preview" data-transform-demo-image @transform="recordImage" @transform.once="imageOnce++">
      <template #previewActions="info"><div class="transform-demo-toolbar"><component :is="info.originNode" /><Button html-type="button" @click="cycleBounds">Cycle preview bounds</Button></div></template>
    </Image>
    <ImagePreviewGroup class="image-demo-thumbnails" :preview="preview" @transform="recordGroup" @transform.once="groupOnce++">
      <Image :src="first" alt="Transform event group first" :width="140" :height="86" data-transform-demo-group-first />
      <Image :src="second" alt="Transform event group second" :width="140" :height="86" />
      <template #previewActions="info"><div class="transform-demo-toolbar"><component :is="info.originNode" /><Button html-type="button" @click="cycleBounds">Cycle preview bounds</Button></div></template>
    </ImagePreviewGroup>
    </div>
    <p>Image events: {{ imageChanges }} (once: {{ imageOnce }}); group events: {{ groupChanges }} (once: {{ groupOnce }}).</p>
    <pre>{{ last ? JSON.stringify(last, null, 2) : 'No transform yet' }}</pre>
    <output data-image-transform-demo-state hidden>{{ JSON.stringify({ imageChanges, groupChanges, imageOnce, groupOnce, last }) }}</output>
  </section>
</template>

<style scoped>
.transform-demo-toolbar { display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: var(--apollo-padding-xs); }
.transform-demo-toolbar > button { color: var(--apollo-color-text); background: var(--apollo-color-bg-container); }
</style>
```

### thumbnail-groups.css

```css
/* Keep grouped thumbnails distinct when the Demo canvas wraps to a narrow width. */
.image-demo-gallery,
.image-demo-thumbnails {
  display: flex;
  flex-wrap: wrap;
  align-items: flex-start;
  gap: 12px;
  min-width: 0;
  max-width: 100%;
}
```

## fallback (fallback)

加载失败时显示 `fallback` 指定的图片。

### fallback.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/fallback.tsx
import { Image } from '@apollo-design/ui';

const fallback =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
</script>

<template>
  <Image :width="200" :height="200" alt="fallback image" src="error" :fallback="fallback" />
</template>
```

## 全局预览样式 (popup-provider)

Image与PreviewGroup都读取 `ConfigProvider.components.image.classNames.popup/styles.popup`。按钮替换整个components map：空 → A → B → 移除；打开预览后也可通过工具栏按钮更新，预览和当前变换保持。

类名按Provider、局部顺序拼接；popup样式按字段浅合并，局部 `styles.popup.root` 会替换Provider的整个root样式对象，其他未覆盖字段仍保留。原生class/style仅落在图片或Group实际根，不复制到弹层。配置是静态数据对象，支持字段/对象替换、晚出现和移除。

方向按钮在ltr/rtl间切换Provider，Group导航图标读取当前方向并镜像。未自定义的图标继续使用默认图标；Prev/Next仍表达前后索引请求，按钮名称保持。

### popup-provider.vue

```vue
<script setup lang="ts">
import './thumbnail-groups.css';
import {
  Button,
  ConfigProvider,
  type ConfigProviderProps,
  Image,
  ImagePreviewGroup,
  type ImageSemanticType,
} from '@apollo-design/ui';
import { ref, shallowRef } from 'vue';

const phase = ref(0);
const direction = ref<'ltr' | 'rtl'>('ltr');
const toggleDirection = () => {
  direction.value = direction.value === 'ltr' ? 'rtl' : 'ltr';
};
const labels = ['empty', 'A', 'B', 'removed'];
const components = shallowRef<NonNullable<ConfigProviderProps['components']>>({});
const source = `data:image/svg+xml;charset=utf-8,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="240" height="140"><rect width="240" height="140" fill="#38598b"/></svg>')}`;
function cycle() {
  phase.value = (phase.value + 1) % labels.length;
  const mode = phase.value === 1 ? 'A' : phase.value === 2 ? 'B' : undefined;
  const image: ImageSemanticType = {
    classNames: {
      popup: {
        root: `popup-demo-${mode}`,
        mask: `popup-demo-${mode}-mask`,
        close: `popup-demo-${mode}-close`,
      },
    },
    styles: {
      popup: {
        root: {
          '--popup-demo-mode': mode ?? '',
          boxShadow: `inset 0 0 0 var(--apollo-line-width-bold) var(--apollo-color-${mode === 'A' ? 'primary' : 'success'}-border)`,
        },
        mask: { '--popup-demo-mask': mode ?? '' },
        close: {
          outline: `var(--apollo-line-width) solid var(--apollo-color-${mode === 'A' ? 'primary' : 'success'}-border)`,
        },
      },
    },
  };
  components.value = mode ? { image: { ...image } } : {};
}
</script>

<template>
  <section data-image-popup-provider-demo>
    <div style="display: flex; flex-wrap: wrap; gap: 8px">
    <Button html-type="button" @mousedown.prevent @click="cycle">Cycle popup provider</Button>
    <Button html-type="button" @mousedown.prevent @click="toggleDirection">Toggle provider icon direction</Button>
    </div>
    <p>Navigation icon direction: <output data-popup-demo-direction>{{ direction }}</output>.</p>
    <p>Current provider: <output data-popup-demo-mode>{{ labels[phase] }}</output>. Open either preview; its toolbar can update the same provider while it stays open.</p>
    <ConfigProvider :components="components" :direction="direction">
      <div class="image-demo-gallery">
<Image :src="source" alt="Provider standalone preview" :width="160" :height="94"
        :class-names="{ popup: { root: 'popup-demo-local' } }" data-popup-demo-image>
        <template #previewActions="info">
          <div class="popup-demo-toolbar"><component :is="info.originNode" /><Button html-type="button" @click="cycle">Cycle popup provider</Button><Button html-type="button" @click="toggleDirection">Toggle provider icon direction</Button></div>
        </template>
      </Image>
      <ImagePreviewGroup class="image-demo-thumbnails" :class-names="{ popup: { root: 'popup-demo-local' } }">
        <Image :src="source" alt="Provider group first" :width="140" :height="82" data-popup-demo-group />
        <Image :src="source" alt="Provider group second" :width="140" :height="82" />
        <template #previewActions="info">
          <div class="popup-demo-toolbar"><component :is="info.originNode" /><Button html-type="button" @click="cycle">Cycle popup provider</Button><Button html-type="button" @click="toggleDirection">Toggle provider icon direction</Button></div>
        </template>
      </ImagePreviewGroup>
    </div>
    </ConfigProvider>
  </section>
</template>

<style scoped>
.popup-demo-toolbar { display: flex; flex-wrap: wrap; justify-content: center; align-items: center; gap: var(--apollo-margin-xs); }
.popup-demo-toolbar > button { color: var(--apollo-color-text); background: var(--apollo-color-bg-container); }
</style>
```

### thumbnail-groups.css

```css
/* Keep grouped thumbnails distinct when the Demo canvas wraps to a narrow width. */
.image-demo-gallery,
.image-demo-thumbnails {
  display: flex;
  flex-wrap: wrap;
  align-items: flex-start;
  gap: 12px;
  min-width: 0;
  max-width: 100%;
}
```

## image-render (image-render)

使用原生 `#imageRender="info"` 模板扩展图片。通过 `<component :is="info.originNode" />` 保留真实 img、当前图源、尺寸、语义类名与加载机制，并显示当前说明。

更新按钮同时改变说明、alt、尺寸和本地 data URI 图源；相同结构下图片和输入草稿、焦点保持。插槽存在但有意为空时不恢复默认图片，移除插槽才恢复当前默认 img。第一部分主动关闭预览，用于观察原生组件事件；第二部分保留默认预览，group根内有独立可见的原生预览按钮，originNode保持普通img。输入和保存按钮可直接编辑，无需.stop；图片及非交互封面可点击预览，封面按钮保留原生点击，说明文字可选择。

外根使用有名称、可聚焦的 `role="group"`，通过标准 Vue `@click`、`@keydown`、`@error` 及各自的 `.once` 监听器显示次数和原始事件类型。输入框停止点击与键盘事件冒泡；关闭预览时，点击或按键不会触发 `update:open`，其计数保持为零。

顶层 `imageRender` 函数声明直接迁为此原生插槽，没有函数 prop 兼容通道；预览配置内部的同名字段不属于此次迁移。

第三部分完全替换originNode，仍提供独立可见的原生预览按钮，保留键盘入口；空槽不会补出此按钮。封面原生按钮使用主题文字/背景色，说明使用secondary文字以保持可读对比度。

### image-render.vue

```vue
<script setup lang="ts">
import { Button, Image } from '@apollo-design/ui';
import { computed, h, ref, shallowRef } from 'vue';

const svgSource = (color: string, label: string) =>
  `data:image/svg+xml;charset=utf-8,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="240" height="140" viewBox="0 0 240 140"><rect width="240" height="140" fill="${color}"/><text x="120" y="76" text-anchor="middle" font-family="sans-serif" font-size="22" fill="white">${label}</text></svg>`)}`;
const firstSource = svgSource('#38598b', 'First image');
const nextSource = svgSource('#297373', 'Current image');
const revision = ref(0);
const show = ref(true);
const empty = ref(false);
const loads = ref(0);
const errors = ref(0);
const clicks = ref(0);
const clickOnce = ref(0);
const keydowns = ref(0);
const keydownOnce = ref(0);
const errorOnce = ref(0);
const openUpdates = ref(0);
const richOpened = ref(false);
const richDraft = ref('Editable caption');
const richSaved = ref(0);
const richCover = ref(false);
const artworkDraft = ref('Custom artwork note');
const richPreview = computed(() => ({
  cover: richCover.value
    ? h(
        'button',
        {
          type: 'button',
          style: {
            color: 'var(--apollo-color-text)',
            backgroundColor: 'var(--apollo-color-bg-container)',
          },
          onClick: () => richSaved.value++,
        },
        'Save cover caption',
      )
    : undefined,
}));
const lastClick = shallowRef<MouseEvent>();
const lastKeydown = shallowRef<KeyboardEvent>();
const lastError = shallowRef<Event>();
const lastOpen = ref<boolean>();
const src = computed(() => (revision.value % 2 === 0 ? firstSource : nextSource));
const alt = computed(() => `Custom image ${revision.value}`);
const width = computed(() => 200 + revision.value * 20);
const height = computed(() => 120 + revision.value * 10);
const eventState = computed(() => ({
  clicks: clicks.value,
  clickOnce: clickOnce.value,
  keydowns: keydowns.value,
  keydownOnce: keydownOnce.value,
  errors: errors.value,
  errorOnce: errorOnce.value,
  openUpdates: openUpdates.value,
  lastOpen: lastOpen.value ?? null,
  lastClickType: lastClick.value?.constructor.name ?? 'none',
  lastClickNative: lastClick.value ? lastClick.value instanceof MouseEvent : null,
  lastKeydownType: lastKeydown.value?.constructor.name ?? 'none',
  lastKeydownNative: lastKeydown.value ? lastKeydown.value instanceof KeyboardEvent : null,
  lastKey: lastKeydown.value?.key ?? 'none',
  lastErrorType: lastError.value?.constructor.name ?? 'none',
  lastErrorNative: lastError.value ? lastError.value instanceof Event : null,
}));

function onImageClick(event: MouseEvent) {
  clicks.value++;
  lastClick.value = event;
}

function onImageKeydown(event: KeyboardEvent) {
  keydowns.value++;
  lastKeydown.value = event;
}

function onImageError(event: Event) {
  errors.value++;
  lastError.value = event;
}

function onImageOpenUpdate(open: boolean) {
  openUpdates.value++;
  lastOpen.value = open;
}
</script>

<template>
  <section data-image-render-demo :data-image-event-state="JSON.stringify(eventState)">
    <p style="display: flex; flex-wrap: wrap; gap: 8px">
      <Button html-type="button" @mousedown.prevent @click="revision++">Update image content</Button>
      <Button html-type="button" @mousedown.prevent @click="empty = !empty">Empty image render slot</Button>
      <Button html-type="button" @mousedown.prevent @click="show = !show">Toggle image render slot</Button>
    </p>
    <Image :alt="alt" :width="width" :height="height" :src="src" :title="`Image title ${revision}`" :preview="false"
      data-image-event-root role="group" aria-label="Custom image event group" :tabindex="0"
      :class-names="{ image: `native-render-image-${revision}` }"
      :styles="{ root: { height: 'auto' }, image: { objectFit: 'cover' } }"
      @click="onImageClick" @click.once="clickOnce++"
      @keydown="onImageKeydown" @keydown.once="keydownOnce++"
      @error="onImageError" @error.once="errorOnce++" @update:open="onImageOpenUpdate">
      <template v-if="show" #imageRender="info">
        <figure v-if="!empty" class="image-render-frame" data-native-image-render
          :data-image-src="info.src" :data-image-title="info.title" :data-image-class="info.classNames.image">
          <component :is="info.originNode" @load="loads++" />
          <figcaption data-native-image-caption>Caption {{ revision }} · {{ info.alt }} · {{ info.width }} × {{ info.height }}</figcaption>
          <input aria-label="Image render note" @click.stop @keydown.stop />
        </figure>
      </template>
    </Image>
    <p>Native load events: <output data-image-render-loads>{{ loads }}</output>; errors: <output data-image-render-errors>{{ errors }}</output> (<output data-image-event-error-once>{{ errorOnce }}</output> once); last error: <output data-image-event-error-type>{{ eventState.lastErrorType }}</output>.</p>
    <p>Clicks: <output data-image-event-clicks>{{ clicks }}</output> (<output data-image-event-click-once>{{ clickOnce }}</output> once); last event: <output data-image-event-click-type>{{ eventState.lastClickType }}</output>.</p>
    <p>Keydowns: <output data-image-event-keydowns>{{ keydowns }}</output> (<output data-image-event-keydown-once>{{ keydownOnce }}</output> once); last event: <output data-image-event-keydown-type>{{ eventState.lastKeydownType }}</output>, key: <output data-image-event-key>{{ eventState.lastKey }}</output>.</p>
    <p>Preview open updates: <output data-image-event-open-updates>{{ openUpdates }}</output>. Preview is disabled; the input keeps its own click and keyboard events.</p>
    <section data-image-rich-preview>
      <p><Button html-type="button" @click="richCover = !richCover">Toggle interactive cover</Button></p>
      <Image v-model:open="richOpened" :src="firstSource" alt="Rich preview image" :width="200" :preview="richPreview">
        <template #imageRender="{ originNode }">
          <figure class="image-render-frame">
            <component :is="originNode" />
            <figcaption>Preview the image and edit its caption.</figcaption>
            <input v-model="richDraft" aria-label="Preview thumbnail caption" />
            <Button html-type="button" @click="richSaved++">Save thumbnail caption</Button>
          </figure>
        </template>
      </Image>
      <p>Saved: <output data-image-rich-saved>{{ richSaved }}</output>; preview open: <output data-image-rich-open>{{ richOpened }}</output>.</p>
    </section>
    <section data-image-custom-preview>
      <Image :src="firstSource" alt="Custom artwork preview" :width="200">
        <template #imageRender>
          <div class="image-render-frame">
            <p>Custom artwork replaces the thumbnail.</p>
            <input v-model="artworkDraft" aria-label="Custom artwork note" />
          </div>
        </template>
      </Image>
    </section>
  </section>
</template>

<style scoped>
.image-render-frame {
  display: flex;
  flex-direction: column;
  gap: var(--apollo-margin-xs);
  margin: 0;
}
.image-render-frame figcaption {
  color: var(--apollo-color-text-secondary);
}
.image-render-frame input {
  box-sizing: border-box;
  width: 100%;
}
</style>
```

## preview-close (preview-close)

Image 与 PreviewGroup 通过原生 `#previewCloseIcon` 定制关闭图标。槽存在时优先于 `preview.closeIcon` 和 `preview.icons.close`，有意为空也不回退；移除槽恢复配置或默认图标。按钮独立保留可访问名称。

示例在槽图标、空槽、VNode 配置、隐藏按钮和默认图标间循环。`preview.closable=false` 只隐藏关闭按钮且不求值图标槽；Esc、遮罩和工具栏关闭动作仍按各自契约工作。打开时切换不会重挂图片、清除编辑内容或复位变换。

### preview-close.vue

```vue
<script setup lang="ts">
import './thumbnail-groups.css';
import { Button, Image, ImagePreviewGroup, Input, type PreviewConfig } from '@apollo-design/ui';
import { computed, h, ref } from 'vue';

const phase = ref(0);
const labels = ['slot', 'empty slot', 'data', 'hidden', 'default'];
const note = ref('Editable preview note');
const imageOpen = ref(false);
const groupOpen = ref(false);
const source = `data:image/svg+xml;charset=utf-8,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="240" height="140"><rect width="240" height="140" fill="#38598b"/></svg>')}`;
const preview = computed<PreviewConfig>(() => ({
  closable: phase.value !== 3,
  closeIcon:
    phase.value === 2
      ? h('span', { 'aria-hidden': 'true', 'data-close-demo-icon': 'data' }, '×')
      : undefined,
}));
function cycle() {
  phase.value = (phase.value + 1) % labels.length;
}
</script>

<template>
  <section data-image-close-demo>
    <Button html-type="button" data-close-demo-cycle @mousedown.prevent @click="cycle">Cycle close control</Button>
    <p>Close control: <output data-close-demo-phase>{{ labels[phase] }}</output>. Escape and the mask can still close a preview when its close button is hidden.</p>
    <div class="image-demo-gallery">
<Image v-model:open="imageOpen" :src="source" alt="Close control image" :width="160" :height="94" :preview="preview" data-close-demo-image>
      <template v-if="phase === 0 || phase === 1" #previewCloseIcon><span v-if="phase === 0" aria-hidden="true" data-close-demo-icon="slot">×</span></template>
      <template #previewImage="info"><figure class="close-demo-frame"><component :is="info.originNode" /><Input v-model:value="note" aria-label="Close control note" /></figure></template>
      <template #previewActions="info"><div class="close-demo-actions"><component :is="info.originNode" /><Button html-type="button" @mousedown.prevent @click="cycle">Cycle close control</Button></div></template>
    </Image>
    <ImagePreviewGroup class="image-demo-thumbnails" v-model:open="groupOpen" :preview="preview">
      <Image :src="source" alt="Close control group first" :width="140" :height="82" data-close-demo-group />
      <Image :src="source" alt="Close control group second" :width="140" :height="82" />
      <template v-if="phase === 0 || phase === 1" #previewCloseIcon><span v-if="phase === 0" aria-hidden="true" data-close-demo-icon="slot">×</span></template>
      <template #previewImage="info"><figure class="close-demo-frame"><component :is="info.originNode" /><Input v-model:value="note" aria-label="Close control note" /></figure></template>
      <template #previewActions="info"><div class="close-demo-actions"><component :is="info.originNode" /><Button html-type="button" @mousedown.prevent @click="cycle">Cycle close control</Button></div></template>
    </ImagePreviewGroup>
    </div>
    <output data-close-demo-state hidden>{{ JSON.stringify({ phase, imageOpen, groupOpen, note }) }}</output>
  </section>
</template>

<style scoped>
.close-demo-frame { display: flex; flex-direction: column; align-items: center; gap: var(--apollo-padding-xs); margin: 0; }
.close-demo-frame input, .close-demo-actions > button { color: var(--apollo-color-text); background: var(--apollo-color-bg-container); }
.close-demo-actions { display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: var(--apollo-padding-xs); }
</style>
```

### thumbnail-groups.css

```css
/* Keep grouped thumbnails distinct when the Demo canvas wraps to a narrow width. */
.image-demo-gallery,
.image-demo-thumbnails {
  display: flex;
  flex-wrap: wrap;
  align-items: flex-start;
  gap: 12px;
  min-width: 0;
  max-width: 100%;
}
```

## nested (nested)

嵌套在其他容器中的图片（预览浮层仍挂 portal）。

### nested.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/nested.tsx —— 浮层挂 portal，不受父容器 overflow 影响
import { Image } from '@apollo-design/ui';

const src =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
</script>

<template>
  <div style="overflow: hidden; width: 200px; height: 120px">
    <Image alt="demo image" :width="200" :height="120" :src="src" />
  </div>
</template>
```

## placeholder (placeholder)

使用 `placeholder.progress` 展示生成进度（无 `percent` 时为忙碌态）。

### placeholder.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/placeholder.tsx —— 进度占位（percent 由使用方推进）
import { Image } from '@apollo-design/ui';
import { onMounted, onUnmounted, ref } from 'vue';

const percent = ref(-1);
let timer: ReturnType<typeof setTimeout> | undefined;

onMounted(() => {
  const tick = () => {
    percent.value = Math.min(percent.value + 8, 100);
    if (percent.value < 100) timer = setTimeout(tick, 200);
  };
  timer = setTimeout(tick, 200);
});
onUnmounted(() => clearTimeout(timer));
</script>

<template>
  <Image alt="demo image"
    :width="200"
    :height="200"
    :placeholder="{ progress: { percent: percent === -1 ? undefined : percent } }"
  />
</template>
```

## preview-group (preview-group)

多个图片放在 `Image.PreviewGroup` 中，可切换预览。

默认计数在主题背景上显示，遮罩关闭时也保持文字对比；背景取自 `colorBgSpotlight`。

### preview-group.vue

```vue
<script setup lang="ts">
import './thumbnail-groups.css';
import { Button, Image } from '@apollo-design/ui';
import { ref } from 'vue';

const src =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
const PreviewGroup = Image.PreviewGroup;
const images = ref([1, 2, 3]);
const current = ref(0);
const removeCurrent = () => {
  images.value.splice(current.value, 1);
};
const reset = () => {
  images.value = [1, 2, 3];
  current.value = 0;
};
</script>

<template>
  <section data-image-group-ownership style="display: flex; flex-direction: column; align-items: flex-start; gap: 12px">
    <Button html-type="button" @click="reset">Reset group</Button>
    <PreviewGroup class="image-demo-thumbnails" v-model:current="current">
      <Image v-for="i in images" :key="i" :alt="`Group image ${i}`" :width="200" :src="src" />
      <template #previewImage="{ originNode }">
        <component :is="originNode" />
        <Button html-type="button" :disabled="images.length < 2" @click="removeCurrent">Remove current thumbnail</Button>
      </template>
    </PreviewGroup>
  </section>
</template>
```

### thumbnail-groups.css

```css
/* Keep grouped thumbnails distinct when the Demo canvas wraps to a narrow width. */
.image-demo-gallery,
.image-demo-thumbnails {
  display: flex;
  flex-wrap: wrap;
  align-items: flex-start;
  gap: 12px;
  min-width: 0;
  max-width: 100%;
}
```

## preview-group-top-progress (preview-group-top-progress)

通过原生 `#previewImage`、`#previewActions` 与 `#previewCount` 扩展预览大图、工具栏和计数。每个槽接收单对象信息，`originNode` 为原始VNode；用 `<component :is="info.originNode" />` 保留现有图片手势或默认工具栏。

示例保留可编辑说明及组内状态，工具栏用typed `actions.reset/zoomIn` 操作。`current` 为零基索引，显示时加1。空槽抑制默认内容，移除槽恢复默认。旧preview配置的imageRender/actionsRender/countRender及toolbarRender别名直接移除，无兼容层。

### preview-group-top-progress.vue

```vue
<script setup lang="ts">
import './thumbnail-groups.css';
import { Button, Image, ImagePreviewGroup, Input, type TransformInfo } from '@apollo-design/ui';
import { computed, ref, shallowRef } from 'vue';

const custom = ref(true);
const empty = ref(false);
const revision = ref(0);
const open = ref(false);
const current = ref(0);
const note = ref('A note that survives image changes');
const transformed = shallowRef<TransformInfo>();
const svg = (color: string, text: string) =>
  `data:image/svg+xml;charset=utf-8,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="240" height="140"><rect width="240" height="140" fill="${color}"/><text x="120" y="76" text-anchor="middle" font-family="sans-serif" font-size="20" fill="white">${text}</text></svg>`)}`;
const first = computed(() =>
  svg(revision.value % 2 ? '#6b4b7a' : '#38598b', `First ${revision.value}`),
);
const second = svg('#297373', 'Second');
</script>

<template>
  <section data-image-preview-slots-demo>
    <p style="display: flex; flex-wrap: wrap; gap: 8px">
      <Button html-type="button" @mousedown.prevent @click="custom = !custom">Toggle custom preview slots</Button>
      <Button html-type="button" @mousedown.prevent @click="empty = !empty">Empty preview slots</Button>
      <Button html-type="button" @mousedown.prevent @click="revision++">Update preview sources</Button>
    </p>
    <ImagePreviewGroup class="image-demo-thumbnails" v-model:open="open" v-model:current="current" @transform="info => transformed = info">
      <Image :src="first" :alt="`Preview slot first ${revision}`" :width="180" :height="105" data-preview-demo-first />
      <Image :src="second" alt="Preview slot second" :width="180" :height="105" />
      <template v-if="custom" #previewImage="info">
        <figure v-if="!empty" data-preview-demo-image>
          <component :is="info.originNode" />
          <figcaption>{{ info.alt }} · {{ info.current + 1 }} / {{ info.total }}</figcaption>
          <Input v-model:value="note" aria-label="Preview caption" />
        </figure>
      </template>
      <template v-if="custom" #previewActions="info">
        <section v-if="!empty" data-preview-demo-actions>
          <component :is="info.originNode" />
          <Button html-type="button" @click="info.actions.reset">Reset preview transform</Button>
          <Button html-type="button" :disabled="info.disabled.zoomIn" @click="info.actions.zoomIn">Custom preview zoom</Button>
        </section>
      </template>
      <template v-if="custom" #previewCount="info">
        <p v-if="!empty" data-preview-demo-count>Image {{ info.current + 1 }} of {{ info.total }}</p>
      </template>
    </ImagePreviewGroup>
    <p>Preview {{ open ? 'open' : 'closed' }}; selected index {{ current }}.</p>
    <output data-image-preview-slots-demo-state hidden>{{ JSON.stringify({ custom, empty, revision, open, current, note, transformed }) }}</output>
  </section>
</template>

<style scoped>
[data-preview-demo-image] { display: flex; flex-direction: column; align-items: center; gap: 8px; margin: 0; padding: var(--apollo-padding-sm); color: var(--apollo-color-text); background: var(--apollo-color-bg-container); }
[data-preview-demo-image] input { color: var(--apollo-color-text); background: var(--apollo-color-bg-container); }
[data-preview-demo-actions] { display: flex; flex-wrap: wrap; justify-content: center; align-items: center; gap: 8px; }
[data-preview-demo-actions] > button { color: var(--apollo-color-text); background: var(--apollo-color-bg-container); }
[data-preview-demo-count] { padding: var(--apollo-padding-xs); text-align: center; color: var(--apollo-color-text); background: var(--apollo-color-bg-container); }
</style>
```

### thumbnail-groups.css

```css
/* Keep grouped thumbnails distinct when the Demo canvas wraps to a narrow width. */
.image-demo-gallery,
.image-demo-thumbnails {
  display: flex;
  flex-wrap: wrap;
  align-items: flex-start;
  gap: 12px;
  min-width: 0;
  max-width: 100%;
}
```

## preview-group-visible (preview-group-visible)

通过顶层 `v-model:open` 与 `v-model:current` 同步预览开关和当前图片索引。父组件按钮可直接打开、关闭或选择下一张；预览内部的关闭与切换则通过模型回传，并分别触发 `@open-change(next, prev)`、`@change(next, prev)`。示例显示当前模型与事件的前后状态，父组件直接赋值不触发组件变更事件。

状态不再放入 `preview` 配置，也不使用 `visible` 或配置对象内的回调。

### preview-group-visible.vue

```vue
<script setup lang="ts">
import { Button, Image } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const current = ref(0);
const openChanges = ref(0);
const lastOpenChange = ref('none');
const currentChanges = ref(0);
const lastCurrentChange = ref('none');
const src =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
const PreviewGroup = Image.PreviewGroup;
const items = [src, src, src].map((source, index) => ({
  src: source,
  alt: `Controlled group image ${index + 1}`,
}));

function onOpenChange(next: boolean, prev: boolean) {
  openChanges.value++;
  lastOpenChange.value = `${prev} → ${next}`;
}

function onChange(next: number, prev: number) {
  currentChanges.value++;
  lastCurrentChange.value = `${prev} → ${next}`;
}
</script>

<template>
  <section data-image-group-model-demo style="display: flex; flex-direction: column; row-gap: 8px; align-items: flex-start">
    <Button html-type="button" aria-haspopup="dialog" :aria-expanded="open" @mousedown.prevent @click="open = !open">
      {{ open ? 'Close controlled group preview' : 'Open controlled group preview' }}
    </Button>
    <Button html-type="button" @mousedown.prevent @click="current = (current + 1) % items.length">Next image from parent</Button>
    <PreviewGroup
      v-model:open="open"
      v-model:current="current"
      :items="items"
      @open-change="onOpenChange"
      @change="onChange"
    />
    <p>Parent open model: <output data-image-group-open>{{ open }}</output>; current index: <output data-image-group-current>{{ current }}</output>.</p>
    <p>Component open changes: <output data-image-group-open-changes>{{ openChanges }}</output>; previous → next: <output data-image-group-open-transition>{{ lastOpenChange }}</output>.</p>
    <p>Component image changes: <output data-image-group-current-changes>{{ currentChanges }}</output>; previous → next: <output data-image-group-current-transition>{{ lastCurrentChange }}</output>.</p>
  </section>
</template>
```

## preview-img-info (preview-img-info)

预览时保留原图的 `width`/`height`（`imageInfo`）。

### preview-img-info.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/preview-imgInfo.tsx
import { Image } from '@apollo-design/ui';

const src =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
</script>

<template>
  <Image alt="demo image" :width="200" :height="120" :src="src" :preview="{ src }" />
</template>
```

## preview-mask (preview-mask)

动态切换遮罩blur、className、style及false；同步演示当前scaleStep和getContainer。打开后可用工具栏按钮切换，保持同一预览与变换。显式容器优先于Provider，移除覆盖恢复默认容器。

### preview-mask.vue

```vue
<script setup lang="ts">
import { Button, Checkbox, Image, type PreviewConfig } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const phase = ref(0);
const container = ref<HTMLElement | null>(null);
const local = ref(false);
const preview = computed<PreviewConfig>(() => ({
  mask:
    phase.value === 2
      ? false
      : {
          blur: phase.value === 0,
          className: 'image-demo-mask',
          style: { background: phase.value === 0 ? 'rgb(20 35 55 / 70%)' : 'rgb(40 25 45 / 60%)' },
        },
  scaleStep: phase.value === 0 ? 0.5 : 0.25,
  ...(local.value && container.value
    ? { getContainer: () => container.value ?? document.body }
    : {}),
}));

const src =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
</script>

<template>
  <section data-image-mask-demo>
    <div>
      <Button html-type="button" @mousedown.prevent @click="phase = (phase + 1) % 3">Cycle mask and zoom step</Button>
      <Checkbox v-model:checked="local">Use local preview container</Checkbox>
    </div>
    <Image alt="Mask configuration example" :width="200" :src="src" :preview="preview">
      <template #previewActions="info">
        <component :is="info.originNode" />
        <div class="image-demo-mask-controls">
          <Button html-type="button" @click="phase = (phase + 1) % 3">Cycle mask and zoom step</Button>
          <output>Step: {{ preview.scaleStep }}</output>
        </div>
      </template>
    </Image>
    <div ref="container" data-image-mask-container />
  </section>
</template>

<style>
.image-demo-mask-controls { display: flex; align-items: center; gap: var(--apollo-margin-xs); padding: var(--apollo-padding-xs); color: var(--apollo-color-text-light-solid); background: var(--apollo-color-bg-spotlight); }
.image-demo-mask-controls button { color: var(--apollo-color-text); background: var(--apollo-color-bg-container); }
</style>
```

## preview-src (preview-src)

`preview.src` 指定预览用的大图（与缩略图不同）。

### preview-src.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/previewSrc.tsx
import { Image } from '@apollo-design/ui';

const src =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
</script>

<template>
  <Image alt="demo image" :width="200" :src="src" :preview="{ src }" />
</template>
```

---

# Input

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/input


# Input 输入框

基本的表单输入控件。包含 `Input` / `TextArea` / `Input.Password` / `Input.Group` /
`Input.Search` / `Input.OTP`。

## 代码演示


## API · Input

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value | 受控值（`v-model:value`） | string | - |
| defaultValue | 初始值 | string | - |
| size | 尺寸 | `large` \| `middle` \| `small` | - |
| disabled / readOnly | 禁用 / 只读 | boolean | false |
| variant | 形态变体 | `outlined` \| `filled` \| `borderless` \| `underlined` | `outlined` |
| status | 校验状态 | `error` \| `warning` | - |
| prefix / suffix | 前后缀内容；`#prefix` / `#suffix` 插槽优先，已存在的空插槽也会覆盖 prop | VNodeChild / Component | - |
| allowClear | 清空按钮（可 `{ clearIcon, disabled }`） | boolean \| object | false |
| showCount | 字数统计（可 `{ formatter }`） | boolean \| object | false |
| count | 计数策略 / 超长裁剪 | object | - |
| maxLength | 原生最大长度 | number | - |
| htmlSize | 原生 `size` | number | - |
| type | 原生输入类型 | string | text |
| placeholder / autoComplete | 原生提示文本 / 自动填充 | string | - |
| autoFocus / hidden | 原生自动聚焦 / 隐藏逻辑根 | boolean | false |
| prefixCls | 输入框类名前缀 | string | Provider 的 input 前缀 |
| ~~clearIcon~~ | **Deprecated** 使用 `allowClear.clearIcon`；对象内未给图标时仍回退到此字段及 Provider | VNodeChild / Component | - |
| classNames / styles | 语义化（root/prefix/suffix/clear/input/count） | object \| function | - |
| ~~bordered~~ | **Deprecated** 用 `variant` | boolean | true |
| ~~addonBefore / addonAfter~~ | **Deprecated** 用 `Space.Compact` | VNodeChild | - |

### 事件

`update:value(value: string)` 和 `change(event: Event)` 在普通输入时同步发出；`change` 中的 `target` 是实际编辑器，`target.value` 为计数处理后的值。IME 组合期间保留原生草稿，仅在结束时提交一次 model / change，并忽略紧随的重复 input。`input` 仍是原生输入事件，包含组合期间的输入。

`press-enter(event: KeyboardEvent)` 在组合期间不触发；`clear(event: MouseEvent)` 由清空按钮触发。清空顺序为写入空值并更新 model → `clear` → 在实际编辑器派发原生 `input`，其处理链触发 `change`。区分清空请监听 `clear`，不要检查 `change.type === 'click'`。

`focus`、`blur`、`keydown`、`keyup`、`mousedown`、`compositionstart` / `compositionend` 等原生监听器传给编辑器。保留 `composition-start` / `composition-end` 的现有监听名。语义事件及原生事件都支持 Vue 的监听器数组和 `.once`。

### Ref

`focus(option)`（含 `cursor: 'start' \| 'end' \| 'all'`）、`blur()`、
`setSelectionRange()`、`select()`、`input`、`nativeElement`。`input` 为实际 input；`nativeElement` 为承载根 class/style 的逻辑根（有 addon 时为 group，有前后缀时为 affix，否则为 input）。动态插槽、清空及计数开关保留编辑节点、焦点和选区。

## API · TextArea

共享 Input 的 value/defaultValue、size、disabled/readOnly、variant/status、allowClear/clearIcon、count/showCount、maxLength、placeholder、autoComplete、hidden 及语义事件。没有 prefix/suffix/addon、htmlSize 或 type API。原生 textarea attrs（例如 `name`、`id`、`aria-*`、`autofocus`）传给实际 textarea。

增加 `autoSize`（`true` 或 `{ minRows, maxRows }`）、`rows` 与 `resize({ width, height })`。resize 返回编辑器外框尺寸，autoSize、原生拖拽及调用方尺寸变化都会通知，相同尺寸去重；卸载清理观察和 document 监听。

语义区域为 `{ root, textarea, clear, count, affixWrapper, variant }`，样式区域为 `{ root, textarea, clear, count }`。Ref 为 `focus()`、`blur()`、`resizableTextArea.textArea` 和逻辑根 `nativeElement`。

## API · Input.Password

`action` 为 `'click' | 'hover'`，默认 `'click'`。hover 在进入按钮边界时切换，子图标 mouseover 不会重复切换；原生按钮保留键盘激活能力。

`visibilityToggle` 默认为 `true`，可设 `false` 或 `{ visible, onVisibleChange, tabIndex, action }`。提供 `visible` 时显隐受控；顶层 `action` 优先于对象内同名字段。`#icon="{ visible }"` 渲染切换图标，`classNames.icon` 作用于按钮。`#prefix` / `#suffix` 与 Input 相同；suffix 插槽只替换用户后缀，切换按钮由 `visibilityToggle` 管理。

继承有效的 Input 属性并增加 `inputPrefixCls`，其 `prefixCls` 作用于 Password。`type` 始终由显隐状态决定，已从 Password 公开接口移除；`iconRender` 已迁移为 icon 插槽。迁移说明见仓库 `docs/migrations/input-contracts.md`。

## API · Input.Search

在 Input 基础上增加：

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| enterButton | 搜索按钮：`false` 图标 / `true` 主按钮 / 文本 / 自定义节点 | boolean \| string \| number \| VNodeChild \| Component | false |
| searchIcon | 自定义搜索图标 | VNodeChild \| Component | `<SearchOutlined />` |
| loading | 按钮 loading；拦截 Enter 和按钮搜索，含自定义按钮 | boolean | false |
| onSearch | 搜索回调 `(value, event, { source })`；清空触发时 `source='clear'` | function | - |
| inputPrefixCls | 内层 Input 的前缀 | string | - |
| addonAfter | 按钮后追加的节点 | VNodeChild \| Component | - |

语义槽：`{ root, input, prefix, suffix, clear, count, button }`（`button` 支持对象或
`{ root }` 形态）。自定义原生按钮保留其 disabled；自定义组件需转发传入的 attrs 和状态。普通内容节点与数组由按钮承载。

保留 Input 的 `type`，默认 `search`，并转发 `#prefix` / `#suffix`。`search(value, event, { source })` 支持 `.once`；source 为 `input` 或 `clear`。`nativeElement` 为外层 Compact 根，`input` 为编辑器；原生 `class` / `style` / `hidden` 和 data attrs 作用于该外层根，其余原生字段作用于编辑器。

## API · Input.OTP

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| length | 格子数量；取正整数，至少 1，非有限值回退 6 | number | 6 |
| value / defaultValue | 受控值 / 初始值（`v-model:value`） | string | - |
| onChange | 全部填满且值变化时触发 | `(value: string) => void` | - |
| onInput | 每次格子变化时触发（数组） | `(value: string[]) => void` | - |
| formatter | 对值做格式化（如转大写） | `(value: string) => string` | - |
| separator | 静态格间内容（包括 `0`）；动态内容使用 `#separator="{ index }"` | VNodeChild | - |
| mask | 掩码（`true` 用 •，或单字符） | boolean \| string | false |
| type / inputMode / autoComplete | 透传给每格原生 input | string | - |
| autoFocus | 聚焦第一格 | boolean | false |
| classNames / styles | 语义槽 `{ root, input, separator }` | object \| function | - |

每次编辑更新 `v-model:value`（包括部分输入），`input` 发出格子数组，`change` 只在完整值变化时发出。受控值被父级拒绝时保持父值。formatter 处理后按 Unicode 码点截到 length；粘贴后移到实际目标格，左右方向键随 RTL 方向移动。

Ref：`focus()`、`blur()`、`nativeElement`（OTP 容器）。

## API · Input.Group

保留 `prefixCls`、`size`、`compact` 和默认插槽。compact 切换组布局；size 向子组件提供默认尺寸。Group 不提供 value、语义事件或编辑器 Ref。已废弃，请使用 `Space.Compact`。

## 主题、尺寸与样式

默认字号、非负内边距及聚焦阴影消费当前主题。`theme.components.Input` 支持既有的 19 个字段：`lineWidthFocus`、`paddingBlock/SM/LG`、`paddingInline/SM/LG`、`addonBg`、`activeBorderColor`、`hoverBorderColor`、`activeShadow`、`errorActiveShadow`、`warningActiveShadow`、`hoverBg`、`activeBg`、`inputFontSize/SM/LG`、`inputAffixPadding`。长度字段可用数字（px）或 CSS 长度字符串，`0` 有效；移除配置后恢复当前主题默认值。`inputAffixPadding` 控制前后缀间距。公开 `prepareInputComponentToken` 继续返回指定数值快照的准备结果。

尺寸优先级为组件显式 `size` → 最近的 `Space.Compact` / `Input.Group` → `ConfigProvider.componentSize`。Group 的尺寸向子组件提供默认值，子组件显式尺寸优先。Input 保留自然行盒，不压缩显式字体、行高或 padding：默认主题 small/middle/large 为 24/32/40px，compact 为 22/28/35px；small 的自然下限可高于主题目标 `controlHeightSM`。不同类型控件没有外框高度恒等承诺。Search 默认按钮随输入自然伸展，不注入自有最小高度；调用方的 `height` / `min-height` 按其 CSS 生效。TextArea 继续按 rows、已有最小高度及 autoSize 约束排版；autoSize 在主题、尺寸、控件及祖先 class/style、宽度变化和排版过渡结束后，根据实际量测签名重测。无关样式变化不重复量测，禁用和卸载会清理观察与事件。

语义 classNames/styles 回调读取当前完整属性及合并后的 size、disabled、variant、status。组件主题数据先于显式语义样式和原生 `style` 合并。`components.input/textArea/inputPassword` 的 `style` 作用于组件逻辑根；`styles.input` / `styles.textarea` 作用于实际控制节点。Search、OTP 的原生根样式作用于容器，格子或输入节点请使用 `styles.input`。既有 stylesheet 的 `--apollo-input-*` 覆盖继续有效；theme 中显式组件字段以逻辑根内联变量提供。

显式空的 `ThemeProvider :theme="{}"`（或 `createThemeContext({})`）仍是默认主题来源，可在外部 CSS 主题作用域内重置默认值。没有有效主题来源时，Input 保留 CSS-only 变量继承；无 theme 的 ConfigProvider 继续读取最近有效来源，不凭空覆盖 CSS 作用域。

## 注意事项

- 输入法组合期间不做计数裁剪，`compositionend` 后才统一裁剪并触发一次 `change`。
- 清空和密码切换使用可键盘操作、带当前语言名称的原生按钮；清空按钮的 `change` 事件里 `target.value` 固定为空串。
- 清空图标只在 undefined 时继续回退；null、false、0 均是显式内容。禁用、只读或空值时清空按钮不可操作。
- `Input.Group` 已废弃，请用 `Space.Compact`。


## 基本 (basic)

基本用法。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/basic.tsx

import { Input } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
</script>

<template>
  <div style="font-family: sans-serif; width: 240px">
    <Input v-model:value="value" placeholder="Basic usage" />
  </div>
</template>
```

## 三种大小 (size)

三种大小的输入框。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/size.tsx
import { Input } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif; display: flex; flex-direction: column; gap: 8px; width: 240px">
    <Input placeholder="large" size="large" />
    <Input placeholder="default" />
    <Input placeholder="small" size="small" />
  </div>
</template>
```

## 前缀 / 后缀 (presuffix)

通过 `prefix` / `suffix` 添加前后缀。

### presuffix.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/presuffix.tsx —— prefix/suffix 支持 prop（string/VNode）与插槽两种用法。
import { UserOutlined } from '@apollo-design/icons';
import { Input } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif; display: flex; flex-direction: column; gap: 8px; width: 260px">
    <Input prefix="¥" suffix="RMB" placeholder="prefix & suffix (prop)" />
    <Input suffix="%" placeholder="suffix only (prop)" />
    <Input placeholder="prefix & suffix (slot)">
      <template #prefix><UserOutlined /></template>
      <template #suffix>
        <span style="color: var(--apollo-color-text-secondary)">单位</span>
      </template>
    </Input>
  </div>
</template>
```

## 可清空 (allow-clear)

`allow-clear` 显示清空按钮；清空的 `change` 事件里 `target.value` 是空串。

### allow-clear.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/allow-clear.tsx

import { Input } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('clear me');
</script>

<template>
  <div style="font-family: sans-serif; width: 240px">
    <Input v-model:value="value" allow-clear placeholder="allowClear" />
  </div>
</template>
```

## 字数统计 (show-count)

`show-count` 显示字数；`count` 可定制计数策略与超长裁剪。

### show-count.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/show-count.tsx

import { Input } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
</script>

<template>
  <div style="font-family: sans-serif; display: flex; flex-direction: column; gap: 8px; width: 240px">
    <Input v-model:value="value" show-count :max-length="20" placeholder="show count" />
  </div>
</template>
```

## 文本域 (textarea)

`TextArea` 支持 `autoSize` 自适应高度与 `showCount`。

两个文本域分别提供可访问名称，示例宽度随容器收缩。

### textarea.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/textarea.tsx（autoSize）

import { TextArea } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px; width: min(100%, 320px)">
    <TextArea
      v-model:value="value"
      aria-label="自适应高度的文本域"
      :auto-size="{ minRows: 2, maxRows: 6 }"
      placeholder="autoSize"
    />
    <TextArea aria-label="带字数统计的文本域" placeholder="showCount" show-count :max-length="50" />
  </div>
</template>
```

## 密码框 (password)

`InputPassword` 可切换明文/密文。

### password.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/password.tsx

import { InputPassword } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
</script>

<template>
  <div style="font-family: sans-serif; width: 240px">
    <InputPassword v-model:value="value" placeholder="input password" />
  </div>
</template>
```

## 形态与状态 (variant-status)

四形态变体与 error / warning 校验状态。

### variant-status.vue

```vue
<script setup lang="ts">
// 形态变体与校验状态
import { Input } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif; display: flex; flex-direction: column; gap: 8px; width: 240px">
    <Input placeholder="filled" variant="filled" />
    <Input placeholder="borderless" variant="borderless" />
    <Input placeholder="underlined" variant="underlined" />
    <Input placeholder="error" status="error" />
    <Input placeholder="warning" status="warning" />
  </div>
</template>
```

## 搜索框 (search)

带搜索按钮的输入框；支持 `enterButton`（图标 / 文本 / 自定义节点）。

通过 Vue 的 `@search` 接收搜索事件，回车与搜索按钮共用同一处理函数。

### search.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/search.tsx
import { InputSearch } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
const lastSearch = ref('');

function onSearch(next: string): void {
  lastSearch.value = next;
}
</script>

<template>
  <div style="width: min(100%, 360px); display: flex; flex-direction: column; gap: 12px">
    <InputSearch
      v-model:value="value"
      allow-clear
      placeholder="input search text"
      @search="onSearch"
    />
    <InputSearch enter-button placeholder="input search text" @search="onSearch" />
    <InputSearch enter-button="Search" placeholder="input search text" @search="onSearch" />
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">last search: {{ lastSearch || '-' }}</div>
  </div>
</template>
```

## 验证码 (otp)

分段验证码输入；支持 `length`、`mask`、`separator` 静态内容、`#separator="{ index }"` 插槽、`formatter` 与键盘导航。

`v-model:value` 在每次编辑时同步部分值，`change` 只在所有格子填满且值变化时触发。

### otp.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/otp.tsx
import { InputOTP } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
const masked = ref('');
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <div>
      <div style="margin-bottom: 8px; color: var(--apollo-color-text-secondary)">basic</div>
      <InputOTP v-model:value="value" aria-label="验证码" />
    </div>
    <div>
      <div style="margin-bottom: 8px; color: var(--apollo-color-text-secondary)">mask + separator</div>
      <InputOTP v-model:value="masked" mask aria-label="隐藏验证码">
        <template #separator="{ index }">{{ index === 2 ? '/' : '-' }}</template>
      </InputOTP>
    </div>
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">values: {{ value || '-' }} / {{ masked || '-' }}</div>
  </div>
</template>
```

## 带前后缀 (addon)

用 `Space.Compact` + `SpaceAddon` 在输入框两侧放置固定内容，替代已废弃的 `addonBefore` / `addonAfter`。

### addon.vue

```vue
<script setup lang="ts">
// addonBefore / addonAfter 已 deprecated，推荐改用 Space.Compact + SpaceAddon
import { Input, SpaceAddon, SpaceCompact } from '@apollo-design/ui';
import { ref } from 'vue';

const site = ref('apollo');
const amount = ref('');
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: min(100%, 320px)">
    <SpaceCompact>
      <SpaceAddon>https://</SpaceAddon>
      <Input v-model:value="site" aria-label="站点前缀" />
      <SpaceAddon>.com</SpaceAddon>
    </SpaceCompact>
    <SpaceCompact>
      <SpaceAddon>￥</SpaceAddon>
      <Input v-model:value="amount" aria-label="金额" placeholder="金额" />
      <SpaceAddon>RMB</SpaceAddon>
    </SpaceCompact>
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">
      site：{{ site || '-' }}；amount：{{ amount || '-' }}
    </div>
  </div>
</template>
```

## 进阶计数 (advance-count)

使用 `count.show`、`count.max`、`count.strategy` 与 `count.exceedFormatter` 定制计数口径和超长裁剪。

### advance-count.vue

```vue
<script setup lang="ts">
// count.show / count.max / count.strategy / count.exceedFormatter 的进阶用法
import { Input, TextArea } from '@apollo-design/ui';
import { ref } from 'vue';

const basic = ref('');
const chinese = ref('');
const note = ref('');

/** 汉字按 2 个字符计数，其余按 1 个。 */
function countChinese(value: string): number {
  let count = 0;
  for (const char of value) {
    count += /[一-龥]/u.test(char) ? 2 : 1;
  }
  return count;
}

/** 超出 max 时按与 strategy 相同的口径截断（汉字占 2 个名额）。 */
function cutAtMax(value: string, info: { max: number }): string {
  let result = '';
  let count = 0;
  for (const char of value) {
    const size = /[一-龥]/u.test(char) ? 2 : 1;
    if (count + size > info.max) break;
    count += size;
    result += char;
  }
  return result;
}
</script>

<template>
  <div
    style="display: flex; flex-direction: column; gap: 16px; width: min(100%, 320px); font-family: sans-serif"
  >
    <div>
      <div style="margin-bottom: 6px; font-size: 13px; color: var(--apollo-color-text-secondary)">count.show + max</div>
      <Input
        v-model:value="basic"
        :count="{ show: true, max: 10 }"
        placeholder="最多 10 个字符"
      />
    </div>
    <div>
      <div style="margin-bottom: 6px; font-size: 13px; color: var(--apollo-color-text-secondary)">
        自定义 strategy：汉字算 2 个字符
      </div>
      <Input
        v-model:value="chinese"
        :count="{ show: true, max: 10, strategy: countChinese, exceedFormatter: cutAtMax }"
        placeholder="汉字算 2 个"
      />
    </div>
    <div>
      <div style="margin-bottom: 6px; font-size: 13px; color: var(--apollo-color-text-secondary)">TextArea 同样支持 count</div>
      <TextArea
        v-model:value="note"
        :count="{ show: true, max: 20 }"
        :auto-size="{ minRows: 2, maxRows: 4 }"
        placeholder="最多 20 个字符"
      />
    </div>
  </div>
</template>
```

## 对齐 (align)

通过根元素的 `style.textAlign` 让输入文本左对齐、居中或右对齐。

### align.vue

```vue
<script setup lang="ts">
// 对齐方式：通过根元素 style 的 text-align 控制输入文本对齐
import { Input } from '@apollo-design/ui';
import { ref } from 'vue';

const left = ref('left aligned');
const center = ref('center aligned');
const right = ref('right aligned');
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px; width: 280px; font-family: sans-serif">
    <Input v-model:value="left" aria-label="左对齐输入框" style="text-align: left" />
    <Input v-model:value="center" aria-label="居中对齐输入框" style="text-align: center" />
    <Input v-model:value="right" aria-label="右对齐输入框" style="text-align: right" />
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">继续输入可查看三种文本对齐效果</div>
  </div>
</template>
```

## 自适应文本域 (autosize-textarea)

`TextArea` 的 `autoSize` 支持布尔值或 `{ minRows, maxRows }`，让文本域随输入内容自动撑高。

两个文本域分别提供可访问名称。示例宽度随容器收缩，字符数说明使用当前主题的次要文字色。

### autosize-textarea.vue

```vue
<script setup lang="ts">
// TextArea autoSize：随内容自动撑高，可用 minRows / maxRows 限定范围
import { TextArea } from '@apollo-design/ui';
import { ref } from 'vue';

const autoValue = ref('');
const rangeValue = ref('');
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: min(100%, 340px)">
    <TextArea
      v-model:value="autoValue"
      aria-label="随内容自动增高的文本域"
      :auto-size="true"
      placeholder="autoSize: true"
    />
    <TextArea
      v-model:value="rangeValue"
      aria-label="限制为二至六行的文本域"
      :auto-size="{ minRows: 2, maxRows: 6 }"
      placeholder="minRows: 2 / maxRows: 6"
    />
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">
      当前字符数：{{ rangeValue.length }}（超过 6 行后出现滚动条）
    </div>
  </div>
</template>
```

## 紧凑组合 (group)

用 `Space.Compact` 把 `Input`、`InputNumber` 与 `Button` 拼成无间隙的组合（`Input.Group` 已 deprecated）。

### group.vue

```vue
<script setup lang="ts">
// 紧凑组合：Input.Group 已 deprecated，推荐使用 Space.Compact
import { Button, Input, InputNumber, SpaceCompact } from '@apollo-design/ui';
import { ref } from 'vue';

const keyword = ref('');
const number = ref<number | null>(1);
const message = ref('尚未提交');

function submit(): void {
  message.value = `提交：${keyword.value || '(空)'} / ${number.value ?? '(空)'}`;
}
</script>

<template>
  <div
    style="display: flex; flex-direction: column; gap: 12px; width: min(100%, 420px); font-family: sans-serif"
  >
    <SpaceCompact block>
      <Input v-model:value="keyword" aria-label="关键词" style="flex: 1; min-width: 0" placeholder="关键词" />
      <InputNumber
        v-model:value="number"
        aria-label="数量"
        :min="0"
        :max="10"
        style="width: 100px"
      />
      <Button type="primary" @click="submit">提交</Button>
    </SpaceCompact>
    <SpaceCompact block>
      <Input aria-label="另一种紧凑组合" style="flex: 1; min-width: 0" placeholder="另一种紧凑组合" />
      <Button>查询</Button>
    </SpaceCompact>
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">{{ message }}</div>
  </div>
</template>
```

## 密码可见性 (password-input)

通过 `action`、`visibilityToggle`（含受控 `visible` / `onVisibleChange`）与 `#icon="{ visible }"` 插槽 控制密码显隐方式与图标。

### password-input.vue

```vue
<script setup lang="ts">
// 密码可见性切换：action / visibilityToggle / icon 作用域插槽
import { EyeInvisibleOutlined, EyeOutlined } from '@apollo-design/icons';
import { InputPassword } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('');
const controlledValue = ref('Apollo Design');
const visible = ref(false);

function onVisibleChange(next: boolean): void {
  visible.value = next;
}
</script>

<template>
  <div
    style="display: flex; flex-direction: column; gap: 12px; width: min(100%, 320px)"
  >
    <InputPassword v-model:value="value" placeholder="默认：点击图标切换" />
    <InputPassword placeholder="hover 触发切换" action="hover" />
    <InputPassword placeholder="隐藏切换按钮" :visibility-toggle="false" />
    <InputPassword
      v-model:value="controlledValue"
      placeholder="受控显隐"
      :visibility-toggle="{ visible, onVisibleChange }"
    />
    <InputPassword placeholder="自定义图标">
      <template #icon="{ visible: revealed }">
        <EyeOutlined v-if="revealed" />
        <EyeInvisibleOutlined v-else />
      </template>
    </InputPassword>
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">受控状态：{{ visible ? '明文' : '密文' }}</div>
  </div>
</template>
```

## 搜索加载中 (search-input-loading)

`InputSearch` 的 `loading` 会让搜索按钮进入加载态，并拦截回车触发的重复搜索。

通过 `@search` 开始一次异步搜索；结束后保留输入值，卸载时清理待完成请求。

### search-input-loading.vue

```vue
<script setup lang="ts">
// Input.Search 的 loading 态：搜索期间按钮转圈并拦截重复搜索
import { InputSearch } from '@apollo-design/ui';
import { onBeforeUnmount, ref } from 'vue';

const value = ref('');
const loading = ref(false);
const result = ref('');

let timer: number | undefined;
let seq = 0;

function onSearch(next: string, _event?: Event, info?: { source?: 'clear' | 'input' }): void {
  const current = ++seq;
  window.clearTimeout(timer);

  if (info?.source === 'clear') {
    loading.value = false;
    result.value = '已清空搜索内容';
    return;
  }

  const keyword = next.trim();
  if (!keyword) {
    loading.value = false;
    result.value = '请输入关键词';
    return;
  }

  loading.value = true;
  result.value = '';
  timer = window.setTimeout(() => {
    if (current !== seq) return;
    loading.value = false;
    result.value = `找到 3 条与「${keyword}」相关的结果`;
  }, 1200);
}

onBeforeUnmount(() => {
  seq += 1;
  window.clearTimeout(timer);
});
</script>

<template>
  <div
    style="display: flex; flex-direction: column; gap: 12px; width: min(100%, 380px); font-family: sans-serif"
  >
    <InputSearch
      v-model:value="value"
      enter-button="搜索"
      :loading="loading"
      placeholder="输入关键词后搜索"
      @search="onSearch"
    />
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">
      {{ loading ? '搜索中…' : result || '等待搜索' }}
    </div>
  </div>
</template>
```

## 聚焦与选中 (focus)

通过 `ref` 暴露的 `focus({ cursor })`、`select()` 与 `blur()` 以命令式方式控制输入框焦点和选区。

### focus.vue

```vue
<script setup lang="ts">
// Input ref：focus / blur / select
import type { InputRef } from '@apollo-design/ui';
import { Button, Input, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const inputRef = ref<InputRef | null>(null);
const status = ref('尚未操作');

function focusStart(): void {
  inputRef.value?.focus({ cursor: 'start' });
  status.value = '已聚焦，光标在开头';
}

function selectAll(): void {
  inputRef.value?.select();
  status.value = '已全选输入内容';
}

function blurInput(): void {
  inputRef.value?.blur();
  status.value = '已失焦';
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: min(100%, 320px); font-family: sans-serif">
    <Input ref="inputRef" aria-label="可聚焦输入框" default-value="Apollo Design" />
    <Space wrap>
      <Button @click="focusStart">聚焦到开头</Button>
      <Button @click="selectAll">全选</Button>
      <Button @click="blurInput">失焦</Button>
    </Space>
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">状态：{{ status }}</div>
  </div>
</template>
```

## 紧凑组合 (compact-style)

`Space.Compact` 把 `Input`、`InputNumber` 与 `Button` 拼成无缝组合，并统一圆角与边框。每个输入控件都有 `aria-label`，组合容器使用 `role="group"` 带上可访问名称。

### compact-style.vue

```vue
<script setup lang="ts">
// 紧凑组合：Space.Compact 拼接 Input / InputNumber / Button
import { Button, Input, InputNumber, SpaceCompact } from '@apollo-design/ui';
import { ref } from 'vue';

const email = ref('');
const quantity = ref<number | null>(1);
const result = ref('尚未提交');

function submit(): void {
  result.value = `${email.value || '(空)'} / ${quantity.value ?? '(空)'}`;
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: min(100%, 460px)">
    <div role="group" aria-label="订阅表单">
      <SpaceCompact block>
        <Input
          v-model:value="email"
          aria-label="订阅邮箱"
          placeholder="name@example.com"
          style="flex: 1; min-width: 0"
        />
        <InputNumber
          v-model:value="quantity"
          aria-label="订阅份数"
          :min="1"
          :max="10"
          style="width: 110px"
        />
        <Button type="primary" @click="submit">订阅</Button>
      </SpaceCompact>
    </div>

    <div role="group" aria-label="关键词搜索">
      <SpaceCompact block>
        <Input aria-label="搜索关键词" placeholder="搜索组件" style="flex: 1; min-width: 0" />
        <Button>搜索</Button>
      </SpaceCompact>
    </div>

    <p aria-live="polite" style="margin: 0; color: var(--apollo-color-text-secondary); font-size: 12px">
      提交结果：{{ result }}
    </p>
  </div>
</template>
```

## 组件 Token (component-token)

Input 的 19 个既有组件 Token 可通过 `theme.components.Input` 配置。默认字号与非负 padding 随当前主题派生；不设置固定输入高度。示例切换紧凑主题、垂直内边距和前缀间距，同时用容器选择器覆盖 `--apollo-input-*` 变量，并可切换祖先 class 来改变字号和 padding。Search 按钮随输入伸展，autoSize 文本域在主题、祖先样式和宽度变化后重新量测。显式样式和 CSS 变量继续优先于默认派生。

### component-token.vue

```vue
<script setup lang="ts">
import { compactAlgorithm, type ThemeConfig } from '@apollo-design/theme';
import { Button, ConfigProvider, Input, InputSearch, TextArea } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const compact = ref(false);
const roomy = ref(false);
const ancestorStyle = ref(false);
const theme = computed<ThemeConfig>(() => {
  const input: Record<string, string | number> = {};
  if (roomy.value) {
    input.paddingBlock = 8;
    input.inputAffixPadding = 10;
  }
  return {
    ...(compact.value ? { algorithm: compactAlgorithm } : {}),
    components: { Input: input },
  };
});
</script>

<template>
  <ConfigProvider :theme="theme">
    <div class="demo-input-token" :class="{ 'demo-input-token--ancestor': ancestorStyle }">
      <div class="demo-input-token__controls">
        <Button :aria-pressed="compact" @click="compact = !compact">紧凑主题</Button>
        <Button :aria-pressed="roomy" @click="roomy = !roomy">
          增大内边距与前缀间距
        </Button>
        <Button :aria-pressed="ancestorStyle" @click="ancestorStyle = !ancestorStyle">
          祖先样式切换
        </Button>
      </div>
      <div class="demo-input-token__field">
        <span class="demo-input-token__label">内边距与紫色聚焦态</span>
        <Input aria-label="令牌示例输入框" placeholder="聚焦查看紫色描边" />
      </div>
      <div class="demo-input-token__field">
        <span class="demo-input-token__label">带前缀的输入框</span>
        <Input aria-label="带前缀的令牌示例" prefix="@" default-value="apollo" />
      </div>
      <div class="demo-input-token__field">
        <span class="demo-input-token__label">搜索按钮随输入自然伸展</span>
        <InputSearch aria-label="主题搜索示例" enter-button="搜索" default-value="Apollo" />
      </div>
      <div class="demo-input-token__field">
        <span class="demo-input-token__label">文本域随主题与宽度重新量测</span>
        <TextArea
          aria-label="主题自适应文本域"
          :auto-size="{ minRows: 2, maxRows: 4 }"
          default-value="保留输入内容，切换主题或增大内边距。"
        />
      </div>
      <p class="demo-input-token__hint">
        覆盖 --apollo-input-padding-inline / --apollo-input-hover-border-color /
        --apollo-input-active-border-color / --apollo-input-active-shadow。
        主题配置消费当前字号与间距，显式 CSS 变量继续生效；祖先样式改变后文本域也会重测。
      </p>
    </div>
  </ConfigProvider>
</template>

<style>
.demo-input-token {
  display: flex;
  flex-direction: column;
  gap: 16px;
  width: min(100%, 360px);
}

.demo-input-token__controls {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}


.demo-input-token__field {
  display: flex;
  flex-direction: column;
  gap: 6px;
}

.demo-input-token__label {
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}

.demo-input-token .apollo-input,
.demo-input-token .apollo-input-affix-wrapper {
  --apollo-input-padding-inline: 16px;
  --apollo-input-hover-border-color: color-mix(in srgb, #9254de 85%, var(--apollo-color-text));
  --apollo-input-active-border-color: color-mix(in srgb, #722ed1 75%, var(--apollo-color-text));
  --apollo-input-hover-bg: color-mix(in srgb, #9254de 8%, var(--apollo-color-bg-container));
  --apollo-input-active-bg: var(--apollo-color-bg-container);
  --apollo-input-active-shadow: 0 0 0 2px rgb(114 46 209 / 18%);
}

.demo-input-token__hint {
  margin: 0;
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}

.demo-input-token--ancestor .apollo-input,
.demo-input-token--ancestor .apollo-input-affix-wrapper {
  font-size: 20px;
  padding-block: 10px;
}
</style>
```

## 校验状态 (status)

`status` 支持 `error` 与 `warning`，作用于输入框和文本域。真实表单中通常由 `Form.Item` 的校验结果自动注入，这里直接传入以便单独查看状态样式。

### status.vue

```vue
<script setup lang="ts">
// 校验状态：error / warning，输入框与文本域共用 status
import { Input, TextArea } from '@apollo-design/ui';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: min(100%, 360px)">
    <div style="display: flex; flex-direction: column; gap: 6px">
      <span style="color: var(--apollo-color-text-secondary); font-size: 12px">错误状态</span>
      <Input status="error" aria-label="错误状态输入框" placeholder="请输入有效邮箱" />
    </div>
    <div style="display: flex; flex-direction: column; gap: 6px">
      <span style="color: var(--apollo-color-text-secondary); font-size: 12px">警告状态</span>
      <Input status="warning" aria-label="警告状态输入框" placeholder="该用户名即将过期" />
    </div>
    <div style="display: flex; flex-direction: column; gap: 6px">
      <span style="color: var(--apollo-color-text-secondary); font-size: 12px">文本域错误状态</span>
      <TextArea
        status="error"
        aria-label="错误状态文本域"
        :rows="3"
        placeholder="请至少填写 20 个字符"
      />
    </div>
  </div>
</template>
```

## 语义化样式与类 (style-class)

Input 与 TextArea 各自暴露语义槽位。`classNames` 只负责拼接类名，`styles` 覆盖对应槽位的内联样式；示例分别作用于输入框、前缀包裹层与文本域。

### style-class.vue

```vue
<script setup lang="ts">
// 语义化样式与类：Input / TextArea 各自的槽位
import type { InputProps, TextAreaProps } from '@apollo-design/ui';
import { Input, TextArea } from '@apollo-design/ui';

const inputClassNames: InputProps['classNames'] = {
  root: 'demo-input-style__root',
  input: 'demo-input-style__input',
  affixWrapper: 'demo-input-style__affix',
};

const inputStyles: InputProps['styles'] = {
  input: { color: '#722ed1', fontWeight: 600 },
  affixWrapper: { backgroundColor: '#f9f0ff', color: '#391085' },
};

const textAreaClassNames: TextAreaProps['classNames'] = {
  root: 'demo-input-style__textarea-root',
  textarea: 'demo-input-style__textarea',
};

const textAreaStyles: TextAreaProps['styles'] = {
  textarea: { color: 'var(--apollo-color-text-secondary)' },
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: min(100%, 360px)">
    <Input
      :class-names="inputClassNames"
      :styles="inputStyles"
      prefix="@"
      default-value="apollo"
      aria-label="语义化输入框"
    />
    <TextArea
      :class-names="textAreaClassNames"
      :styles="textAreaStyles"
      :rows="3"
      default-value="语义化槽位可以让类名与样式精确落在 input / textarea 上。"
      aria-label="语义化文本域"
    />
    <p style="margin: 0; color: var(--apollo-color-text-secondary); font-size: 12px">
      input 与 affixWrapper 槽位分别命中输入框和前缀包裹层。
    </p>
  </div>
</template>

<style>
.demo-input-style__input {
  letter-spacing: 0.4px;
}

.demo-input-style__affix {
  border-color: #d3adf7;
}

.demo-input-style__textarea {
  line-height: 1.7;
}
</style>
```

## 文本域缩放 (textarea-resize)

文本域沿用原生 CSS `resize`：`none` 禁止缩放，`horizontal` / `vertical` 限制方向，`both` 允许宽高同时调整。每个示例都带有 `aria-label`，便于辅助技术区分。

示例宽度随可用空间收缩，说明文字使用当前主题的次要文字色。

### textarea-resize.vue

```vue
<script setup lang="ts">
// 文本域缩放：通过原生 resize 控制可调整方向
import { TextArea } from '@apollo-design/ui';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: min(100%, 360px)">
    <div>
      <div style="margin-bottom: 6px; color: var(--apollo-color-text-secondary); font-size: 12px">
        不可缩放（resize: none）
      </div>
      <TextArea
        aria-label="不可缩放的文本域"
        :rows="3"
        default-value="固定尺寸，适合布局稳定的表单。"
        :style="{ resize: 'none' }"
      />
    </div>
    <div>
      <div style="margin-bottom: 6px; color: var(--apollo-color-text-secondary); font-size: 12px">
        仅水平缩放
      </div>
      <TextArea
        aria-label="仅水平缩放的文本域"
        :rows="3"
        default-value="拖动右下角可改变宽度。"
        :style="{ resize: 'horizontal' }"
      />
    </div>
    <div>
      <div style="margin-bottom: 6px; color: var(--apollo-color-text-secondary); font-size: 12px">
        仅垂直缩放
      </div>
      <TextArea
        aria-label="仅垂直缩放的文本域"
        :rows="3"
        default-value="拖动右下角可改变高度。"
        :style="{ resize: 'vertical' }"
      />
    </div>
    <div>
      <div style="margin-bottom: 6px; color: var(--apollo-color-text-secondary); font-size: 12px">
        双向缩放（resize: both）
      </div>
      <TextArea
        aria-label="双向缩放的文本域"
        :rows="3"
        default-value="宽高都可以调整。"
        :style="{ resize: 'both' }"
      />
    </div>
  </div>
</template>
```

## 输入提示 (tooltip)

用 `Tooltip` 包裹 `Input`，在聚焦或悬停时展示输入规则。`trigger="focus"` 让键盘用户也能触发提示；输入框本身保留 `aria-label`。

### tooltip.vue

```vue
<script setup lang="ts">
// 输入提示：Tooltip 包裹 Input，聚焦或悬停时展示说明
import { Input, Tooltip } from '@apollo-design/ui';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: min(100%, 360px)">
    <Tooltip title="用户名支持 4–16 位字母、数字和下划线" trigger="focus">
      <Input aria-label="用户名" placeholder="聚焦查看输入规则" />
    </Tooltip>

    <Tooltip title="我们会向该邮箱发送确认链接">
      <Input aria-label="邮箱" placeholder="悬停查看提示" />
    </Tooltip>

    <p style="margin: 0; color: var(--apollo-color-text-secondary); font-size: 12px">
      第一个输入框使用 focus 触发，键盘用户也能看到提示；第二个使用默认 hover 触发。
    </p>
  </div>
</template>
```

---

# InputNumber

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/input-number


# InputNumber 数字输入框

通过鼠标或键盘，输入范围内的数值。

## 代码演示


## API

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value | 当前值（`v-model:value`），`null` 表示空值 | number \| string \| null | - |
| defaultValue | 初始值 | number \| string | - |
| min | 最小值 | number \| string | - |
| max | 最大值 | number \| string | - |
| step | 每次改变步数，可以为小数 | number \| string | `1` |
| precision | 数值精度，配置 `formatter` 时会以 `formatter` 为准 | number | - |
| formatter | 指定输入框展示值的格式 | function(value, info: { userTyping, input }): string | - |
| parser | 指定从 `formatter` 里转换回数字的方式 | `(displayValue: string \| undefined) => string \| number` | - |
| disabled | 禁用 | boolean | `false` |
| readOnly | 只读 | boolean | `false` |
| keyboard | 是否启用键盘快捷行为 | boolean | `true` |
| controls | 是否显示增减按钮，也可设置自定义箭头图标 | boolean \| { upIcon, downIcon } | `true` |
| mode | 展示输入框或拨轮 | `'input'` \| `'spinner'` | `'input'` |
| stringMode | 字符值模式，开启后支持高精度小数 | boolean | `false` |
| changeOnBlur | 失焦时是否触发 `change`（把超界值回正） | boolean | `true` |
| changeOnWheel | 聚焦时允许滚轮步进 | boolean | `false` |
| decimalSeparator | 小数点 | string | - |
| placeholder | 占位符 | string | - |
| prefix | 前缀 | VNodeChild | - |
| suffix | 后缀 | VNodeChild | - |
| size | 输入框大小 | `large` \| `medium` \| `small` | - |
| status | 设置校验状态 | `'error'` \| `'warning'` | - |
| variant | 形态变体 | `outlined` \| `borderless` \| `filled` \| `underlined` | `outlined` |
| autoFocus | 自动聚焦 | boolean | `false` |
| classNames | 语义化 class（root/prefix/suffix/input/actions，支持函数） | - | - |
| styles | 语义化 style（同上，支持函数） | - | - |
| ~~bordered~~ | **Deprecated** 使用 `variant` 替代 | boolean | `true` |
| ~~addonBefore~~ | **Deprecated** 使用 `Space.Compact` 替代 | VNodeChild | - |
| ~~addonAfter~~ | **Deprecated** 使用 `Space.Compact` 替代 | VNodeChild | - |

### 插槽

| 名称 | 说明 | 作用域 |
| --- | --- | --- |
| prefix | 前缀富内容；优先于 `prefix` prop | 无 |
| suffix | 后缀富内容；优先于 `suffix` prop，反馈图标继续显示 | 无 |

在渲染期读取插槽，支持条件出现/移除及动态内容；明确提供空 slot 不会回退 prop。无 slot 时保留内容 prop；不改变输入节点、数值格式化、步进和 v-model 行为。

### 事件

| 事件 | 说明 | 回调参数 |
| --- | --- | --- |
| change | 变化回调（`v-model:value` 同步发出） | function(value: number \| string \| null) |
| press-enter | 按下回车的回调 | function(e: KeyboardEvent) |
| step | 点击上下箭头、键盘、滚轮的回调。⚠️ `value` 是 `string \| number` —— `stringMode` 下是**字符串** | function(value: string \| number, info: { offset, type: 'up' \| 'down', emitter: 'handler' \| 'keyboard' \| 'wheel' }) |

`change`、`step`、`pressEnter` 均为声明的 Vue 事件，支持模板监听与 `.once`。`@change` 与 `onChange` 是同一监听器通道，接收数值、stringMode 字符串或空值 `null`；外层包装只转发一次，不混入原生 DOM `change`。输入法组合中的 Enter 不提交数值或发送 `press-enter`；原生 `@keydown.prevent` 可以取消该次内部键盘处理。

### 受控值与原生属性

`value !== undefined` 时，用户操作只提议更新；父级未接受的提议不会成为撤控后的值。把 `value` 改为 `undefined` 后保留最后一次实际接收的值；`defaultValue` 只用于初始化，显式 `null` 不会回退到默认值。

原生 `class`、`style` 与鼠标监听器落根容器；`id`、`name`、`tabindex`、label/ARIA、focus/blur、keydown 等原生属性和监听器落实际 input。组件维护数值状态、spinbutton 角色及数值 ARIA。`input` 是内部文本收集通道；监听数值变化请用 `change` / `update:value`。

ConfigProvider 的 `components.inputNumber` 接受 `InputNumberConfig`：`className`、平铺 `style`、`classNames`、`styles`、`variant`。根样式按 Provider 语义样式、Provider 平铺样式、组件语义样式、原生 `style` 的顺序合并，后者覆盖同名属性。函数式语义配置接收当前解析后的 `size`、`disabled`、`controls`、`variant`。

### 组件 Token

通过 `theme.components.InputNumber` 配置；尺寸支持非负数值（转换为 px）或 CSS 长度字符串。当前主题、嵌套覆盖和移除均实时生效，原生 `style` 中的 CSS 变量优先。

| Token | 说明 |
| --- | --- |
| controlWidth | 输入框宽度，默认 `90px` |
| handleWidth / handleFontSize | 步进区域宽度与图标字号 |
| handleVisible | 常规 input 模式：`'auto'` 默认悬停/聚焦显示；`true` 常显；`false` 隐藏 |
| handleBg / handleActiveBg / filledHandleBg | 步进区域、按压及 filled 背景色 |
| handleHoverColor / handleBorderColor | 步进悬停色与边框色 |
| paddingBlock / paddingBlockSM / paddingBlockLG | 三档垂直内边距 |
| paddingInline / paddingInlineSM / paddingInlineLG | 三档水平内边距 |
| inputFontSize / inputFontSizeSM / inputFontSizeLG | 三档输入字号 |
| inputAffixPadding | 前后缀与输入区域的间距 |
| handleOpacity / handleVisibleWidth | 常态透明度与可见宽度，默认从 `handleVisible` 派生 |

### Ref

| 名称 | 说明 |
| --- | --- |
| focus(option) | 获取焦点；`option.cursor` 为 `'start'` \| `'end'` \| `'all'` |
| blur() | 移除焦点 |
| nativeElement | 根 DOM 元素 |

## 注意事项

- 受控模式下 `value` 可以超出 `min` / `max`（以错误样式展示，不回弹）；用户交互产生的值会被钳制回范围内。
- 键入过程中不做 precision 格式化与范围钳制，失焦或回车时统一回正（上游双状态机语义）。
- `parser` 未提供时，中文句号 `。` 会被自动替换为小数点。


## 基本 (basic)

数字输入框，通过鼠标或键盘输入范围内的数值。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/basic.tsx

import { InputNumber } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<number | null>(3);
</script>

<template>
  <!-- 显式钉字体：继承字体差异是平台差异（CHECKLIST 四） -->
  <div style="font-family: sans-serif">
    <InputNumber v-model:value="value" :min="1" :max="10" style="width: 120px" />
  </div>
</template>
```

## 三种大小 (size)

三种大小的数字输入框，`size` 分别为 `large`、`medium`、`small`。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/size.tsx：三种大小
import { InputNumber } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif; display: flex; flex-direction: column; gap: 8px">
    <InputNumber placeholder="large" size="large" style="width: 200px" />
    <InputNumber placeholder="medium" style="width: 200px" />
    <InputNumber placeholder="small" size="small" style="width: 200px" />
  </div>
</template>
```

## 不可用 (disabled)

点击按钮切换可用状态。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/disabled.tsx

import { InputNumber } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<number | null>(3);
</script>

<template>
  <div style="font-family: sans-serif">
    <InputNumber v-model:value="value" :min="1" :max="10" disabled style="width: 120px" />
  </div>
</template>
```

## 高精度小数 (digit)

`string-mode` 开启字符值模式（`change` 返回 string）；`step` 支持小数。

### digit.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/digit.tsx：高精度小数（stringMode）

import { InputNumber } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string | null>('1024');
const precisionValue = ref<number | null>(2.9);
</script>

<template>
  <div style="font-family: sans-serif; display: flex; flex-direction: column; gap: 8px">
    <InputNumber v-model:value="value" string-mode :step="1" style="width: 200px" />
    <InputNumber v-model:value="precisionValue" :step="0.1" :min="0" :max="10" style="width: 200px" />
  </div>
</template>
```

## 格式化展示 (formatter)

通过 `formatter` 格式化展示，`parser` 解析回数值。

### formatter.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/formatter.tsx

import { InputNumber } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<number | null>(1000);

const formatter = (v: number | string): string => `$ ${v}`.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
// ⚠️ 形参允许 `undefined`（上游 `parser?: (displayValue: string | undefined) => T`）
const parser = (v: string | undefined): string => (v ?? '').replace(/\$\s?|(,*)/g, '');
</script>

<template>
  <div style="font-family: sans-serif">
    <InputNumber
      v-model:value="value"
      :formatter="formatter"
      :parser="parser"
      style="width: 200px"
    />
  </div>
</template>
```

## 键盘行为 (keyboard)

使用 `keyboard={false}` 禁用键盘上下键行为。

### keyboard.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/keyboard.tsx：keyboard=false 关闭键盘步进
import { InputNumber } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif">
    <InputNumber :keyboard="false" :min="1" :max="10" style="width: 120px" />
  </div>
</template>
```

## 形态变体 (variant)

四种形态变体：`outlined` / `filled` / `borderless` / `underlined`。

### variant.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/variant.tsx：形态变体
import { InputNumber } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif; display: flex; flex-direction: column; gap: 8px">
    <InputNumber placeholder="outlined" variant="outlined" style="width: 200px" />
    <InputNumber placeholder="filled" variant="filled" style="width: 200px" />
    <InputNumber placeholder="borderless" variant="borderless" style="width: 200px" />
    <InputNumber placeholder="underlined" variant="underlined" style="width: 200px" />
  </div>
</template>
```

## 拨轮 (spinner)

`mode="spinner"` 切换为拨轮形态（上下按钮在两侧）。

### spinner.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/spinner.tsx：拨轮形态
import { InputNumber } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif">
    <InputNumber mode="spinner" :min="0" :max="10" :value="3" style="width: 120px" />
  </div>
</template>
```

## 超出边界 (out-of-range)

受控模式下 `value` 可以超出 `min` / `max`，超出时以错误色展示（不回弹）。

### out-of-range.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/out-of-range.tsx：受控超界标红不回弹

import { InputNumber } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<number | null>(99);
</script>

<template>
  <div style="font-family: sans-serif">
    <InputNumber v-model:value="value" :min="1" :max="10" style="width: 120px" />
  </div>
</template>
```

## 前缀 / 后缀 (presuffix)

用 `#prefix` / `#suffix` 编写富内容模板；slot 存在时优先于内容 prop，空 slot 也不回退。按钮演示条件插槽移除后恢复 prop 内容。

Use `#prefix` / `#suffix` for rich template content. A present slot, including an empty one, overrides its prop. Toggle the slots to restore prop content.

### presuffix.vue

```vue
<script setup lang="ts">
import { Button, InputNumber } from '@apollo-design/ui';
import { ref } from 'vue';

const custom = ref(true);
</script>

<template>
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: 8px">
    <Button @click="custom = !custom">切换模板前后缀 / Toggle slots</Button>
    <InputNumber prefix="$" suffix="USD" aria-label="金额 / Amount" style="width: 200px">
      <template v-if="custom" #prefix><strong>¥</strong></template>
      <template v-if="custom" #suffix><span>元 / CNY</span></template>
    </InputNumber>
    <InputNumber suffix="%" aria-label="百分比 / Percentage" style="width: 200px" />
  </div>
</template>
```

## 自定义状态 (status)

使用 `status` 设置校验状态（`error` / `warning`）。

### status.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/status.tsx
import { InputNumber } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif; display: flex; flex-direction: column; gap: 8px">
    <InputNumber placeholder="error" status="error" style="width: 200px" />
    <InputNumber placeholder="warning" status="warning" style="width: 200px" />
  </div>
</template>
```

## 自定义语义结构的样式和类 (style-class)

`classNames` / `styles` 支持按语义结构（root / input / actions 等）定制。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/style-class.tsx：语义化样式与类
import { InputNumber } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif">
    <InputNumber
      :default-value="1"
      :styles="{ root: { width: '200px' }, input: { color: 'rgb(19, 116, 246)' } }"
    />
  </div>
</template>
```

## 带前后缀 (addon)

用 `Space.Compact` + `Space.Addon` 给数字输入框加上单位前后缀（`addonBefore` / `addonAfter` 已 deprecated）。

### addon.vue

```vue
<script setup lang="ts">
// addonBefore / addonAfter 已 deprecated，推荐用 Space.Compact + Space.Addon 组合
import { InputNumber, SpaceAddon, SpaceCompact } from '@apollo-design/ui';
import { ref } from 'vue';

const price = ref<number | null>(100);
const weight = ref<number | null>(2.5);
</script>

<template>
  <div
    style="display: flex; flex-direction: column; gap: 12px; width: min(100%, 340px); font-family: sans-serif"
  >
    <SpaceCompact>
      <SpaceAddon>￥</SpaceAddon>
      <InputNumber v-model:value="price" :min="0" style="width: 150px" />
      <SpaceAddon>RMB</SpaceAddon>
    </SpaceCompact>
    <SpaceCompact>
      <InputNumber v-model:value="weight" :min="0" :step="0.5" style="width: 150px" />
      <SpaceAddon>kg</SpaceAddon>
    </SpaceCompact>
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">
      价格：{{ price ?? '空' }}；重量：{{ weight ?? '空' }}
    </div>
  </div>
</template>
```

## 增减按钮 (controls)

`controls` 传 `false` 可隐藏增减按钮，传 `{ upIcon, downIcon }` 可替换为自定义图标。

### controls.vue

```vue
<script setup lang="ts">
// controls：关闭增减按钮，或传入自定义上下箭头图标
import { DownOutlined, UpOutlined } from '@apollo-design/icons';
import { InputNumber } from '@apollo-design/ui';
import { h, ref } from 'vue';

const noControls = ref<number | null>(3);
const customControlsValue = ref<number | null>(5);
const customControls = {
  upIcon: h(UpOutlined),
  downIcon: h(DownOutlined),
};
</script>

<template>
  <div
    style="display: flex; flex-direction: column; gap: 12px; width: 260px; font-family: sans-serif"
  >
    <InputNumber v-model:value="noControls" :controls="false" placeholder="controls=false" />
    <InputNumber
      v-model:value="customControlsValue"
      :controls="customControls"
      placeholder="自定义箭头"
    />
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">
      controls=false：{{ noControls ?? '空' }}；自定义箭头：{{ customControlsValue ?? '空' }}
    </div>
  </div>
</template>
```

## 滚轮步进 (change-on-wheel)

开启 `changeOnWheel` 后，输入框聚焦时可用鼠标滚轮改变数值，`onStep` 的 `info.emitter` 会标记来源为 `wheel`。

### change-on-wheel.vue

```vue
<script setup lang="ts">
// changeOnWheel：聚焦后允许鼠标滚轮步进
import type { InputNumberStepInfo, ValueType } from '@apollo-design/ui';
import { InputNumber } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<number | null>(1);
const lastEmitter = ref('');

function onStep(_value: ValueType, info: InputNumberStepInfo): void {
  lastEmitter.value = info.emitter;
}
</script>

<template>
  <div
    style="display: flex; flex-direction: column; gap: 12px; width: min(100%, 300px); font-family: sans-serif"
  >
    <InputNumber
      v-model:value="value"
      change-on-wheel
      :min="0"
      :max="100"
      style="width: 140px"
      @step="onStep"
    />
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">
      当前值：{{ value ?? '空' }}；最近一次步进来源：{{ lastEmitter || '-' }}
    </div>
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">先聚焦输入框，再滚动鼠标滚轮试试</div>
  </div>
</template>
```

## 形态与尺寸 (variant-size)

把 `variant`（`filled` / `outlined` / `borderless` / `underlined`）与 `size`（`large` / `medium` / `small`）组合使用。

### variant-size.vue

```vue
<script setup lang="ts">
// variant 与 size 的组合
import { InputNumber } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<number | null>(6);
</script>

<template>
  <div
    style="display: flex; flex-direction: column; gap: 8px; width: 220px; font-family: sans-serif"
  >
    <InputNumber v-model:value="value" size="large" variant="filled" :min="0" :max="10" />
    <InputNumber v-model:value="value" size="medium" variant="outlined" :min="0" :max="10" />
    <InputNumber v-model:value="value" size="small" variant="borderless" :min="0" :max="10" />
    <InputNumber v-model:value="value" size="middle" variant="underlined" :min="0" :max="10" />
    <div style="font-size: 12px; color: var(--apollo-color-text-secondary)">当前值：{{ value ?? '空' }}</div>
  </div>
</template>
```

## 聚焦控制 (focus)

通过模板 ref 获取 `InputNumberRef`，再调用 `focus()` / `blur()` 控制输入焦点。按钮均为带可见文本的库组件按钮，操作结果通过 `aria-live` 区域播报。

### focus.vue

```vue
<script setup lang="ts">
// 实例方法：通过 ref 调用 focus / blur
import type { InputNumberRef } from '@apollo-design/ui';
import { Button, InputNumber, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const numberRef = ref<InputNumberRef | null>(null);
const status = ref('尚未操作');

function focusNumber(): void {
  numberRef.value?.focus();
  status.value = '已聚焦数字输入框';
}

function blurNumber(): void {
  numberRef.value?.blur();
  status.value = '已让数字输入框失焦';
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: min(100%, 320px)">
    <InputNumber
      ref="numberRef"
      aria-label="可聚焦的数字输入框"
      :default-value="6"
      :min="0"
      :max="20"
      style="width: 180px"
    />
    <Space wrap>
      <Button @click="focusNumber">聚焦</Button>
      <Button @click="blurNumber">失焦</Button>
    </Space>
    <p aria-live="polite" style="margin: 0; color: var(--apollo-color-text-secondary); font-size: 12px">状态：{{ status }}</p>
  </div>
</template>
```

## 组件 Token (component-token)

通过 `theme.components.InputNumber` 设置步进按钮宽度、内边距、箭头颜色与常显状态，并通过当前主题配置聚焦色。组件将有效值映射到根节点的 CSS 变量；原生 `style` 中的变量仍可覆盖它们。

### component-token.vue

```vue
<script setup lang="ts">
import { ConfigProvider, InputNumber } from '@apollo-design/ui';
</script>

<template>
  <div class="demo-input-number-token">
    <span class="demo-input-number-token__label">紫色聚焦态与更宽的步进按钮</span>
    <ConfigProvider
      :theme="{
        token: { colorPrimary: '#722ed1', colorPrimaryHover: '#9254de', controlOutline: 'rgba(114,46,209,0.18)' },
        components: { InputNumber: { controlWidth: 200, handleWidth: 28, handleFontSize: 14, handleVisible: true, paddingInline: 18, handleBg: 'color-mix(in srgb, #722ed1 10%, var(--apollo-color-bg-container))', handleHoverColor: 'var(--apollo-color-primary-text)' } },
      }"
    >
      <InputNumber
        aria-label="自定义令牌数字输入框"
        :default-value="5"
        :min="0"
        :max="20"
      />
    </ConfigProvider>
    <p class="demo-input-number-token__hint">
      通过 theme.components.InputNumber 配置宽度、步进按钮与背景，通过当前主题配置聚焦色。
    </p>
  </div>
</template>

<style>
.demo-input-number-token {
  display: flex;
  flex-direction: column;
  gap: 8px;
  width: min(100%, 360px);
}

.demo-input-number-token__label {
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}

.demo-input-number-token__hint {
  margin: 0;
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

## 形态 / 尺寸 / 状态组合 (variant-size-status)

把 `variant`（filled / outlined / borderless / underlined）、`size`（large / medium / small）与 `status`（error / warning）组合使用。每个示例都包在带可见文本的 `<label>` 中，并补充 `aria-label`。

### variant-size-status.vue

```vue
<script setup lang="ts">
// variant + size + status 的组合矩阵
import { InputNumber } from '@apollo-design/ui';
</script>

<template>
  <div class="demo-input-number-matrix">
    <label class="demo-input-number-matrix__item">
      <span>large / filled</span>
      <InputNumber
        aria-label="大号填充数字输入框"
        size="large"
        variant="filled"
        :default-value="8"
        :min="0"
        :max="20"
      />
    </label>
    <label class="demo-input-number-matrix__item">
      <span>medium / outlined</span>
      <InputNumber
        aria-label="中号描边数字输入框"
        size="medium"
        variant="outlined"
        :default-value="12"
        :min="0"
        :max="20"
      />
    </label>
    <label class="demo-input-number-matrix__item">
      <span>small / borderless + error</span>
      <InputNumber
        aria-label="小号无边框错误数字输入框"
        size="small"
        variant="borderless"
        status="error"
        :default-value="25"
        :min="0"
        :max="20"
      />
    </label>
    <label class="demo-input-number-matrix__item">
      <span>large / underlined + warning</span>
      <InputNumber
        aria-label="大号下划线警告数字输入框"
        size="large"
        variant="underlined"
        status="warning"
        :default-value="18"
        :min="0"
        :max="20"
      />
    </label>
  </div>
</template>

<style>
.demo-input-number-matrix {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr));
  gap: 16px;
  width: min(100%, 520px);
}

.demo-input-number-matrix__item {
  display: flex;
  flex-direction: column;
  gap: 6px;
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

## 拨轮尺寸 (spinner-size)

`mode="spinner"` 把上下箭头换成加减按钮。示例并排展示 `large` / `medium` / `small` 三种尺寸，每个控件都有可见的 `<label>` 文本和 `aria-label`。

### spinner-size.vue

```vue
<script setup lang="ts">
// 拨轮形态的三种尺寸
import { InputNumber } from '@apollo-design/ui';
</script>

<template>
  <div class="demo-input-number-spinner">
    <label class="demo-input-number-spinner__item">
      <span>大号拨轮</span>
      <InputNumber
        aria-label="大号拨轮数字输入框"
        style="width: 180px"
        mode="spinner"
        size="large"
        :default-value="3"
        :min="0"
        :max="10"
      />
    </label>
    <label class="demo-input-number-spinner__item">
      <span>中号拨轮</span>
      <InputNumber
        aria-label="中号拨轮数字输入框"
        style="width: 180px"
        mode="spinner"
        size="medium"
        :default-value="5"
        :min="0"
        :max="10"
      />
    </label>
    <label class="demo-input-number-spinner__item">
      <span>小号拨轮</span>
      <InputNumber
        aria-label="小号拨轮数字输入框"
        style="width: 180px"
        mode="spinner"
        size="small"
        :default-value="7"
        :min="0"
        :max="10"
      />
    </label>
  </div>
</template>

<style>
.demo-input-number-spinner {
  display: flex;
  flex-direction: column;
  gap: 16px;
  width: min(100%, 280px);
}

.demo-input-number-spinner__item {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  color: var(--apollo-color-text-secondary);
  font-size: 12px;
}
</style>
```

---

# Layout

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/layout


使用 Layout、LayoutHeader、LayoutFooter、LayoutContent 和 LayoutSider 组成页面。也保留 Layout.Header / Footer / Content / Sider 静态别名。

## 代码演示


## Layout

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| prefixCls | 完整 DOM 类名前缀 | string | Provider 前缀 + -layout |
| hasSider | 显式 boolean 优先；否则检测当前直接 Sider、数组/Fragment 和已注册 Sider | boolean | 自动检测 |

Header/Footer/Content 只有 prefixCls；显式前缀直接使用，不再附加后缀。Layout/Header/Footer/Content/Sider 分别使用 div/header/footer/main/aside。default 插槽接收完整 Vue 内容，含数组、Fragment 和数字 0；条件内容在 render 中读取。嵌套 Layout 独立登记 Sider。若组件包装隐藏了 SSR 可见的 Sider 结构，可显式指定 hasSider。

## LayoutSider

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| collapsible | 显示折叠触发器 | boolean | false |
| collapsed | 当前折叠状态，支持 v-model:collapsed | boolean | 非受控 |
| defaultCollapsed | 只用于非受控初始化 | boolean | false |
| width | 展开宽度；数字/数字字符串补 px，其他合法 CSS 长度保留 | number 或 string | 200 |
| collapsedWidth | 折叠宽度；零宽时使用侧边触发器 | number 或 string | 80 |
| reverseArrow | 反转图标和零宽触发器方向 | boolean | false |
| trigger | 内置按钮的内容数据；null 隐藏按钮（有 trigger 插槽时插槽优先） | VNodeChild | 默认图标 |
| zeroWidthTriggerStyle | 零宽按钮原生样式 | CSSProperties | — |
| breakpoint | 订阅响应式断点 | xs/sm/md/lg/xl/xxl/xxxl | — |
| theme | 侧边栏与触发器明暗外观 | light 或 dark | dark |
| prefixCls | 完整 DOM 前缀 | string | Provider 前缀 + -layout-sider |
| classNames | root/body 类名，对象或接收当前 { props } 的函数 | SiderSemanticClassNames | — |
| styles | root/body 样式，对象或接收当前 { props } 的函数 | SiderSemanticStyles | — |

受控时点击和断点变化只请求新状态，父级决定是否接受；拒绝请求保持当前 DOM/宽度。解除受控时保留最后已接受值。非受控 defaultCollapsed 后续修改不重置状态。正文不因折叠卸载，输入草稿与组件身份保留。

| Vue 事件 | 载荷 |
| --- | --- |
| update:collapsed | boolean |
| collapse | (collapsed: boolean, type: clickTrigger 或 responsive) |
| breakpoint | broken: boolean |

JavaScript 的 onCollapse/onBreakpoint 继续可用，监听器替换/移除即时生效。业务监听器不再透传为 aside 原生事件；其余原生事件仍作用于根。

媒体监听从 mounted 开始，SSR 不订阅也不发事件。启用断点后立即发送一次当前 breakpoint 状态，状态不同时请求 responsive 折叠；切换断点重新订阅。移除断点清除 below 状态、注销监听，保留当前折叠状态，不补发合成事件；卸载清理全部监听。最大视口阈值依次为 479.98 / 575.98 / 767.98 / 991.98 / 1199.98 / 1599.98 / 1839.98px。

## 插槽、键盘与 ref

Layout 家族的 default 插槽均接收内容。Sider 的 trigger 插槽存在即优先于 trigger 数据，包含有意为空的返回；移除插槽恢复数据或默认图标。trigger / #trigger 是内置原生 button 的内容，请使用文字、图标等非交互内容。自有交互控件请设 trigger=null 并放在 Header 等外部位置，避免嵌套按钮。

默认和零宽按钮均支持 Tab、Enter、Space，type=button，提供展开状态、名称和正文关联。零宽正文设置 inert/aria-hidden，保留内容实例；正文持有焦点时折叠至零宽，焦点移至内置按钮，不抢占外部焦点。自有外部按钮负责自己的名称、状态和焦点。

collapsedWidth 的 CSS 变量/表达式按实际宽度识别零宽，动态恢复非零宽时恢复正文交互。零宽按钮的圆角、边框和位置同时跟随当前方向与 reverseArrow。

五个组件的 ref 仅开放 nativeElement: HTMLElement 或 null。Menu 通过当前 Sider context 消费 collapsed；Menu 的显式 inlineCollapsed 优先。

## 原生 attrs、Provider 与主题

class/style、data-*、ARIA 和原生监听器落根，style 支持 Vue 对象、字符串和数组。Layout 样式顺序为当前主题数据 → components.layout.style → 原生 style。components.layout.className 用于 Layout/Sider；该 Provider style 只配置 Layout 本体。Header/Footer/Content 通过自身 attrs 配置。Sider 样式顺序为主题数据 → styles.root → 原生 style → width/collapsedWidth 几何；宽度通过对应 prop 设置，正文使用 styles.body。

19 个已有 Layout 字段均消费当前 theme.components.Layout，支持 ConfigProvider、ThemeProvider（无需注入全局 CSS）、四主题、嵌套与 SSR。数字长度转 px，有限非负数字含 0 有效，合法字符串长度保留；替换/移除配置恢复当前默认值。

| 字段 | 作用 |
| --- | --- |
| bodyBg | Layout 背景 |
| headerBg/headerColor/headerHeight/headerPadding | Header 背景、文字、外高/行高、内边距 |
| footerBg/footerPadding | Footer 背景与内边距 |
| siderBg | dark Sider 背景 |
| triggerBg/triggerColor/triggerHeight | dark 按钮背景、文字、按钮高/预留空间 |
| zeroTriggerWidth/zeroTriggerHeight | 零宽按钮几何 |
| lightSiderBg/lightTriggerBg/lightTriggerColor | light Sider 和按钮配色 |
| colorBgBody/colorBgHeader/colorBgTrigger | 保留的 deprecated 背景别名，现代字段优先 |

默认 Header 使用深蓝背景与 colorTextLightSolid 文字；深浅 Sider 正文分别使用 colorTextLightSolid/colorText。当前 Alias 派生默认尺寸；显式字段、原生属性与 stylesheet 中既有 --apollo-layout-* 变量继续有效，用户变量优先于主题数据。内部 -source-* 是既有字段的数据通道，不是新增 ComponentToken；不要依赖该内部名称。独立 Header/Footer/Content/Sider 也有完整静态默认值。

同一主题内的家族节点继承外层 Layout 的原生 Alias 覆盖。无 theme 的 ConfigProvider 保留 CSS-only 变量；显式空 ThemeProvider 可隔离远层主题，即使其下又有无配置 ConfigProvider。

## 样式入口

    import '@apollo-design/theme/tokens.css';
    import '@apollo-design/ui/layout/style.css';
    import '@apollo-design/ui/layout-sider/style.css';

Layout/Header/Footer/Content 使用第一个组件入口，Sider 使用独立 layout-sider 入口；或统一引入 ui/style.css。业务槽中的 Menu/Breadcrumb 等仍导入各自 CSS。自定义 prefixCls 只改 DOM 命名，配合预生成 genLayoutStyle/genSiderStyle，不在运行时生成任意前缀 CSS。

公开类型保留 LayoutProps/Ref、SiderProps/Ref、Breakpoint、CollapseType、语义类型，新增所属 LayoutSlots、SiderSlots、SiderEmits。根包中的 Sider 类型使用 LayoutSider 前缀别名。修正与迁移见 docs/migrations/layout-contracts.md。


## 基本结构 (basic)

切换单一预览，比较无侧栏与有侧栏的两种真实布局；每次保留一个有效 main 地标。

### basic.vue

```vue
<script setup lang="ts">
import { Checkbox, Layout } from '@apollo-design/ui';
import { ref } from 'vue';

const { Header, Content, Footer, Sider } = Layout;
const withSider = ref(false);
</script>
<template>
  <div>
    <Checkbox v-model:checked="withSider" style="margin-bottom: 16px">Include sidebar</Checkbox>
    <Layout class="demo-basic">
      <Header>Header</Header>
      <Layout v-if="withSider"><Sider width="25%">Sider</Sider><Content class="demo-basic-content">Content</Content></Layout>
      <Content v-else class="demo-basic-content">Content</Content>
      <Footer>Footer</Footer>
    </Layout>
  </div>
</template>
<style scoped>
.demo-basic { overflow: hidden; border-radius: var(--apollo-border-radius-lg); text-align: center; }
.demo-basic-content { min-height: 120px; padding: 24px; background: var(--apollo-color-primary-bg); }
</style>
```

## 侧边布局 (side)

顶部导航、侧边真实 Menu、Breadcrumb 与内容区组合；Sider 的默认深色表面保持当前可读文字。

### side.vue

```vue
<script setup lang="ts">
import { Breadcrumb, Layout, Menu } from '@apollo-design/ui';

const { Header, Content, Footer, Sider } = Layout;
const nav = [
  { key: 'home', label: 'Overview' },
  { key: 'projects', label: 'Projects' },
  { key: 'settings', label: 'Settings' },
];
const crumbs = [
  { title: 'Home', href: '#/layout-home' },
  { title: 'Projects' },
  { title: 'Details' },
];
</script>
<template><Layout><Header class="demo-header"><strong>Apollo</strong><Menu class="demo-navigation" theme="dark" mode="horizontal" :items="nav" :default-selected-keys="['home']" /></Header><Layout><Sider :width="160"><Menu class="demo-navigation" theme="dark" mode="inline" :items="nav" :default-selected-keys="['projects']" /></Sider><Content class="demo-content"><Breadcrumb class="demo-breadcrumb" :items="crumbs" /><div class="demo-card">Project content</div></Content></Layout><Footer class="demo-footer">Apollo Design · Workspace</Footer></Layout></template>

<style scoped>
.demo-header { display: flex; align-items: center; gap: 16px; padding-inline: 20px; }
.demo-header :deep(.apollo-menu-horizontal) { flex: 1; min-width: 0; }
.demo-content { min-width: 0; padding: 20px; }
.demo-card { min-height: 240px; padding: 20px; background: var(--apollo-color-bg-container); color: var(--apollo-color-text); border-radius: var(--apollo-border-radius-lg); }
.demo-footer { text-align: center; }
.demo-breadcrumb { margin-bottom: 16px; }

:deep(.demo-navigation.apollo-menu-dark) {
  --apollo-menu-item-bg: transparent;
  --apollo-menu-dark-item-bg: transparent;
}
</style>
```

## 顶部布局 (top)

Header 使用真实横向 Menu，Content 使用 Breadcrumb。主题和选中态均保留当前 Alias 配色。

### top.vue

```vue
<script setup lang="ts">
import { Breadcrumb, Layout, Menu } from '@apollo-design/ui';

const { Header, Content, Footer } = Layout;
const nav = [
  { key: 'home', label: 'Overview' },
  { key: 'projects', label: 'Projects' },
  { key: 'settings', label: 'Settings' },
];
const crumbs = [
  { title: 'Home', href: '#/layout-home' },
  { title: 'Projects' },
  { title: 'Details' },
];
</script>
<template><Layout><Header class="demo-header"><strong>Apollo</strong><Menu class="demo-navigation" theme="dark" mode="horizontal" :items="nav" :default-selected-keys="['home']" /></Header><Content class="demo-content"><Breadcrumb class="demo-breadcrumb" :items="crumbs" /><div class="demo-card">Project content</div></Content><Footer class="demo-footer">Apollo Design · Workspace</Footer></Layout></template>

<style scoped>
.demo-header { display: flex; align-items: center; gap: 16px; padding-inline: 20px; }
.demo-header :deep(.apollo-menu-horizontal) { flex: 1; min-width: 0; }
.demo-content { min-width: 0; padding: 20px; }
.demo-card { min-height: 240px; padding: 20px; background: var(--apollo-color-bg-container); color: var(--apollo-color-text); border-radius: var(--apollo-border-radius-lg); }
.demo-footer { text-align: center; }
.demo-breadcrumb { margin-bottom: 16px; }

:deep(.demo-navigation.apollo-menu-dark) {
  --apollo-menu-item-bg: transparent;
  --apollo-menu-dark-item-bg: transparent;
}
</style>
```

## 顶部-侧边布局 (top-side)

真实顶部 Menu 与 light Sider 导航；使用当前主题表面，不写死白色内容区。

### top-side.vue

```vue
<script setup lang="ts">
import { Breadcrumb, Layout, Menu } from '@apollo-design/ui';

const { Header, Content, Footer, Sider } = Layout;
const nav = [
  { key: 'home', label: 'Overview' },
  { key: 'projects', label: 'Projects' },
  { key: 'settings', label: 'Settings' },
];
const crumbs = [
  { title: 'Home', href: '#/layout-home' },
  { title: 'Projects' },
  { title: 'Details' },
];
</script>
<template><Layout><Header class="demo-header"><strong>Apollo</strong><Menu class="demo-navigation" theme="dark" mode="horizontal" :items="nav" :default-selected-keys="['home']" /></Header><Layout><Sider theme="light" :width="160"><Menu class="demo-navigation" mode="inline" :items="nav" :default-selected-keys="['home']" /></Sider><Content class="demo-content"><Breadcrumb class="demo-breadcrumb" :items="crumbs" /><div class="demo-card">Project content</div></Content></Layout><Footer class="demo-footer">Apollo Design · Workspace</Footer></Layout></template>

<style scoped>
.demo-header { display: flex; align-items: center; gap: 16px; padding-inline: 20px; }
.demo-header :deep(.apollo-menu-horizontal) { flex: 1; min-width: 0; }
.demo-content { min-width: 0; padding: 20px; }
.demo-card { min-height: 240px; padding: 20px; background: var(--apollo-color-bg-container); color: var(--apollo-color-text); border-radius: var(--apollo-border-radius-lg); }
.demo-footer { text-align: center; }
.demo-breadcrumb { margin-bottom: 16px; }

:deep(.demo-navigation.apollo-menu-dark) {
  --apollo-menu-item-bg: transparent;
  --apollo-menu-dark-item-bg: transparent;
}
</style>
```

## 顶部-侧边通栏 (top-side-2)

真实分组 Menu 的展开与选中状态，配合 Breadcrumb 展示层级。

### top-side-2.vue

```vue
<script setup lang="ts">
import { Breadcrumb, Layout, Menu } from '@apollo-design/ui';

const { Header, Content, Sider } = Layout;
const nav = [
  { key: 'home', label: 'Overview' },
  { key: 'projects', label: 'Projects' },
  { key: 'settings', label: 'Settings' },
];
const crumbs = [
  { title: 'Home', href: '#/layout-home' },
  { title: 'Projects' },
  { title: 'Details' },
];

const groups = [
  {
    key: 'workspace',
    label: 'Workspace',
    children: [
      { key: 'tasks', label: 'Tasks' },
      { key: 'files', label: 'Files' },
    ],
  },
  {
    key: 'team',
    label: 'Team',
    children: [
      { key: 'members', label: 'Members' },
      { key: 'roles', label: 'Roles' },
    ],
  },
];
</script>
<template><Layout><Header class="demo-header"><strong>Apollo</strong><Menu class="demo-navigation" theme="dark" mode="horizontal" :items="nav" :default-selected-keys="['home']" /></Header><Layout><Sider theme="light" :width="160"><Menu class="demo-navigation" mode="inline" :items="groups" :default-open-keys="['workspace']" :default-selected-keys="['tasks']" /></Sider><Content class="demo-content"><Breadcrumb class="demo-breadcrumb" :items="crumbs" /><div class="demo-card">Project content</div></Content></Layout></Layout></template>

<style scoped>
.demo-header { display: flex; align-items: center; gap: 16px; padding-inline: 20px; }
.demo-header :deep(.apollo-menu-horizontal) { flex: 1; min-width: 0; }
.demo-content { min-width: 0; padding: 20px; }
.demo-card { min-height: 240px; padding: 20px; background: var(--apollo-color-bg-container); color: var(--apollo-color-text); border-radius: var(--apollo-border-radius-lg); }
.demo-footer { text-align: center; }
.demo-breadcrumb { margin-bottom: 16px; }

:deep(.demo-navigation.apollo-menu-dark) {
  --apollo-menu-item-bg: transparent;
  --apollo-menu-dark-item-bg: transparent;
}
</style>
```

## 固定头部 (fixed)

使用 Header 原生 style/CSS 的 sticky 定位，导航仍为真实 Menu。

### fixed.vue

```vue
<script setup lang="ts">
import { Breadcrumb, Layout, Menu } from '@apollo-design/ui';

const { Header, Content, Footer } = Layout;
const nav = [
  { key: 'home', label: 'Overview' },
  { key: 'projects', label: 'Projects' },
  { key: 'settings', label: 'Settings' },
];
const crumbs = [
  { title: 'Home', href: '#/layout-home' },
  { title: 'Projects' },
  { title: 'Details' },
];
</script>
<template><Layout><Header class="demo-header demo-fixed-header"><strong>Apollo</strong><Menu class="demo-navigation" theme="dark" mode="horizontal" :items="nav" :default-selected-keys="['home']" /></Header><Content class="demo-content"><Breadcrumb class="demo-breadcrumb" :items="crumbs" /><div class="demo-card">Project content</div></Content><Footer class="demo-footer">Apollo Design · Workspace</Footer></Layout></template>

<style scoped>
.demo-header { display: flex; align-items: center; gap: 16px; padding-inline: 20px; }
.demo-header :deep(.apollo-menu-horizontal) { flex: 1; min-width: 0; }
.demo-content { min-width: 0; padding: 20px; }
.demo-card { min-height: 800px; padding: 20px; background: var(--apollo-color-bg-container); color: var(--apollo-color-text); border-radius: var(--apollo-border-radius-lg); }
.demo-footer { text-align: center; }
.demo-breadcrumb { margin-bottom: 16px; }

:deep(.demo-navigation.apollo-menu-dark) {
  --apollo-menu-item-bg: transparent;
  --apollo-menu-dark-item-bg: transparent;
}
</style>

<style scoped>.demo-fixed-header { position: sticky; top: 0; z-index: 1; }</style>
```

## 固定侧边栏 (fixed-sider)

使用 Sider 原生 sticky/overflow 样式建立固定导航；正文与页脚保留 Layout 结构。

### fixed-sider.vue

```vue
<script setup lang="ts">
import { Breadcrumb, Layout, Menu } from '@apollo-design/ui';

const { Header, Content, Footer, Sider } = Layout;
const nav = [
  { key: 'home', label: 'Overview' },
  { key: 'projects', label: 'Projects' },
  { key: 'settings', label: 'Settings' },
];
const crumbs = [
  { title: 'Home', href: '#/layout-home' },
  { title: 'Projects' },
  { title: 'Details' },
];
</script>
<template><Layout><Sider class="demo-fixed-sider" :width="160"><Menu class="demo-navigation" theme="dark" mode="inline" :items="nav" :default-selected-keys="['projects']" /></Sider><Layout><Header class="demo-header">Project workspace</Header><Content class="demo-content"><Breadcrumb class="demo-breadcrumb" :items="crumbs" /><div class="demo-card">Project content</div></Content><Footer class="demo-footer">Apollo Design · Workspace</Footer></Layout></Layout></template>

<style scoped>
.demo-header { display: flex; align-items: center; gap: 16px; padding-inline: 20px; }
.demo-header :deep(.apollo-menu-horizontal) { flex: 1; min-width: 0; }
.demo-content { min-width: 0; padding: 20px; }
.demo-card { min-height: 800px; padding: 20px; background: var(--apollo-color-bg-container); color: var(--apollo-color-text); border-radius: var(--apollo-border-radius-lg); }
.demo-footer { text-align: center; }
.demo-breadcrumb { margin-bottom: 16px; }

:deep(.demo-navigation.apollo-menu-dark) {
  --apollo-menu-item-bg: transparent;
  --apollo-menu-dark-item-bg: transparent;
}
</style>

<style scoped>.demo-fixed-sider { position: sticky; top: 0; height: min(100vh, 520px); overflow: auto; }</style>
```

## 自定义触发器 (custom-trigger)

trigger=null 隐藏内置按钮，在 Header 使用有名称与展开状态的真实 Button；v-model:collapsed 控制侧边栏与 Menu。

### custom-trigger.vue

```vue
<script setup lang="ts">
import { MenuFoldOutlined, MenuUnfoldOutlined } from '@apollo-design/icons';
import { Breadcrumb, Button, Layout, Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const { Header, Content, Sider } = Layout;
const collapsed = ref(false);
const nav = [
  { key: 'home', label: 'Overview' },
  { key: 'projects', label: 'Projects' },
  { key: 'settings', label: 'Settings' },
];
const crumbs = [
  { title: 'Home', href: '#/layout-home' },
  { title: 'Projects' },
  { title: 'Details' },
];
</script>
<template><Layout><Sider v-model:collapsed="collapsed" :trigger="null" collapsible :width="160"><Menu class="demo-navigation" theme="dark" mode="inline" :items="nav" :default-selected-keys="['home']" /></Sider><Layout><Header class="demo-header"><Button type="text" :aria-label="collapsed ? 'Expand navigation' : 'Collapse navigation'" :aria-expanded="!collapsed" :icon="h(collapsed ? MenuUnfoldOutlined : MenuFoldOutlined)" class="demo-custom-toggle" @click="collapsed = !collapsed" /></Header><Content class="demo-content"><Breadcrumb class="demo-breadcrumb" :items="crumbs" /><div class="demo-card">Project content</div></Content></Layout></Layout></template>

<style scoped>
.demo-header { display: flex; align-items: center; gap: 16px; padding-inline: 20px; }
.demo-header :deep(.apollo-menu-horizontal) { flex: 1; min-width: 0; }
.demo-content { min-width: 0; padding: 20px; }
.demo-card { min-height: 240px; padding: 20px; background: var(--apollo-color-bg-container); color: var(--apollo-color-text); border-radius: var(--apollo-border-radius-lg); }
.demo-footer { text-align: center; }
.demo-breadcrumb { margin-bottom: 16px; }

:deep(.demo-navigation.apollo-menu-dark) {
  --apollo-menu-item-bg: transparent;
  --apollo-menu-dark-item-bg: transparent;
}
</style>

<style scoped>.demo-custom-toggle { color: inherit; }</style>
```

## 响应式 (responsive)

breakpoint=lg 在挂载时报告当前媒体状态，零宽触发器可用键盘展开；页面显示 breakpoint/collapse 的真实事件结果。

小屏浮动按钮有独立的顶部操作空间，展开与收起时均避开正文；大屏恢复普通内容间距。

### responsive.vue

```vue
<script setup lang="ts">
import { Breadcrumb, Layout, Menu } from '@apollo-design/ui';
import { ref } from 'vue';

const { Header, Content, Footer, Sider } = Layout;
const collapsed = ref(false),
  broken = ref(false),
  source = ref('initial');
const onBreakpoint = (value: boolean) => {
  broken.value = value;
};
const onCollapse = (_value: boolean, type: 'clickTrigger' | 'responsive') => {
  source.value = type;
};
const nav = [
  { key: 'home', label: 'Overview' },
  { key: 'projects', label: 'Projects' },
  { key: 'settings', label: 'Settings' },
];
const crumbs = [
  { title: 'Home', href: '#/layout-home' },
  { title: 'Projects' },
  { title: 'Details' },
];
</script>
<template><Layout><Sider v-model:collapsed="collapsed" breakpoint="lg" :collapsed-width="0" :width="180" @breakpoint="onBreakpoint" @collapse="onCollapse"><Menu class="demo-navigation" theme="dark" mode="inline" :items="nav" :default-selected-keys="['home']" /></Sider><Layout><Header class="demo-header">Responsive workspace</Header><Content class="demo-content" :class="{ 'demo-content-floating': broken }"><Breadcrumb class="demo-breadcrumb" :items="crumbs" /><div class="demo-card"><p>Below breakpoint: {{ broken }}</p><p>Collapsed: {{ collapsed }}</p><p>Source: {{ source }}</p></div></Content><Footer class="demo-footer">Apollo Design · Workspace</Footer></Layout></Layout></template>

<style scoped>
.demo-header { display: flex; align-items: center; gap: 16px; padding-inline: 20px; }
.demo-header :deep(.apollo-menu-horizontal) { flex: 1; min-width: 0; }
.demo-content { min-width: 0; padding: 20px; }
.demo-content-floating { padding-block-start: calc(var(--apollo-control-height-lg) + 20px); }
.demo-card { min-height: 240px; padding: 20px; background: var(--apollo-color-bg-container); color: var(--apollo-color-text); border-radius: var(--apollo-border-radius-lg); }
.demo-footer { text-align: center; }
.demo-breadcrumb { margin-bottom: 16px; }

:deep(.demo-navigation.apollo-menu-dark) {
  --apollo-menu-item-bg: transparent;
  --apollo-menu-dark-item-bg: transparent;
}
</style>
```

## 组件 Token (component-token)

通过当前 ConfigProvider theme.components.Layout 配置已有字段；按钮动态移除配置后回到当前主题默认值。

### component-token.vue

```vue
<script setup lang="ts">
import type { ThemeConfig } from '@apollo-design/theme';
import { Breadcrumb, Button, ConfigProvider, Layout, Menu } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const { Header, Content, Footer, Sider } = Layout;
const custom = ref(true);
const componentFields: Record<string, string | number> = {
  headerBg: 'var(--apollo-color-primary-bg)',
  headerColor: 'var(--apollo-color-text)',
  headerHeight: 72,
  headerPadding: '0 20px',
  footerPadding: '16px 20px',
  siderBg: '#343e59',
  triggerBg: '#343e59',
  triggerHeight: 40,
  zeroTriggerWidth: 36,
  zeroTriggerHeight: 36,
};
const theme = computed<ThemeConfig>(() =>
  custom.value ? { components: { Layout: componentFields } } : {},
);
const nav = [
  { key: 'home', label: 'Overview' },
  { key: 'projects', label: 'Projects' },
  { key: 'settings', label: 'Settings' },
];
const crumbs = [
  { title: 'Home', href: '#/layout-home' },
  { title: 'Projects' },
  { title: 'Details' },
];
</script>
<template>
  <div><Button style="margin-bottom: 16px" @click="custom = !custom">{{ custom ? 'Use default tokens' : 'Use component tokens' }}</Button>
  <ConfigProvider :theme="theme"><Layout><Header class="demo-header">Current Layout tokens</Header><Layout><Sider collapsible :width="160"><Menu class="demo-navigation" theme="dark" mode="inline" :items="nav" :default-selected-keys="['projects']" /></Sider><Content class="demo-content"><Breadcrumb class="demo-breadcrumb" :items="crumbs" /><div class="demo-card">Project content</div></Content></Layout><Footer class="demo-footer">Apollo Design · Workspace</Footer></Layout></ConfigProvider></div>
</template>

<style scoped>
.demo-header { display: flex; align-items: center; gap: 16px; padding-inline: 20px; }
.demo-header :deep(.apollo-menu-horizontal) { flex: 1; min-width: 0; }
.demo-content { min-width: 0; padding: 20px; }
.demo-card { min-height: 240px; padding: 20px; background: var(--apollo-color-bg-container); color: var(--apollo-color-text); border-radius: var(--apollo-border-radius-lg); }
.demo-footer { text-align: center; }
.demo-breadcrumb { margin-bottom: 16px; }

:deep(.demo-navigation.apollo-menu-dark) {
  --apollo-menu-item-bg: transparent;
  --apollo-menu-dark-item-bg: transparent;
}
</style>
```

## 可收起浮层 (collapsible-overlay)

使用原生绝对定位的覆盖式 Sider；零宽时保留正文实例并移出键盘/无障碍树，内置按钮可反复展开。

正文顶部预留浮动按钮的操作空间，避免按钮遮挡面包屑；该间距随当前主题的控件尺寸变化。

### collapsible-overlay.vue

```vue
<script setup lang="ts">
import { Breadcrumb, Layout, Menu } from '@apollo-design/ui';
import { ref } from 'vue';

const { Header, Content, Footer, Sider } = Layout;
const collapsed = ref(false);
const nav = [
  { key: 'home', label: 'Overview' },
  { key: 'projects', label: 'Projects' },
  { key: 'settings', label: 'Settings' },
];
const crumbs = [
  { title: 'Home', href: '#/layout-home' },
  { title: 'Projects' },
  { title: 'Details' },
];
</script>
<template><Layout class="demo-overlay"><Sider v-model:collapsed="collapsed" collapsible :collapsed-width="0" :width="180" class="demo-overlay-sider"><Menu class="demo-navigation" theme="dark" mode="inline" :items="nav" :default-selected-keys="['home']" /></Sider><Layout><Header class="demo-header">Overlay navigation</Header><Content class="demo-content"><Breadcrumb class="demo-breadcrumb" :items="crumbs" /><div class="demo-card">Project content</div></Content><Footer class="demo-footer">Apollo Design · Workspace</Footer></Layout></Layout></template>

<style scoped>
.demo-header { display: flex; align-items: center; gap: 16px; padding-inline: 20px; }
.demo-header :deep(.apollo-menu-horizontal) { flex: 1; min-width: 0; }
.demo-content { min-width: 0; padding: 20px; padding-block-start: calc(var(--apollo-control-height-lg) + 20px); }
.demo-card { min-height: 240px; padding: 20px; background: var(--apollo-color-bg-container); color: var(--apollo-color-text); border-radius: var(--apollo-border-radius-lg); }
.demo-footer { text-align: center; }
.demo-breadcrumb { margin-bottom: 16px; }

:deep(.demo-navigation.apollo-menu-dark) {
  --apollo-menu-item-bg: transparent;
  --apollo-menu-dark-item-bg: transparent;
}
</style>

<style scoped>
.demo-overlay { position: relative; min-height: 360px; }
.demo-overlay-sider { position: absolute; inset-block: 0; inset-inline-start: 0; z-index: 2; }
</style>
```

---

# List

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/list


通用列表。

List 按 Apollo 的独立契约维护；逐项内容使用带类型的 Vue `#item` 插槽。

## 何时使用

- 需要展示一组同构数据（新闻列表、用户列表、搜索结果）时；
- 需要分页、栅格排布、竖向图文混排时。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/list/demo)（**12 个**，覆盖 antd 的主要用户场景）。

| demo | 内容 |
|---|---|
| `basic` | 基础列表（`Item.Meta` 的头像 / 标题 / 描述三段） |
| `simple` | 三档尺寸 + 页头 / 页脚 / 边框 |
| `vertical` | `itemLayout="vertical"` 的两段式 + `actions` + 分页 |
| `grid` | `grid.column` 的栅格排布 |
| `responsive` | `grid` 的断点列数 |
| `loadmore` | `loadMore` 取代底部分页 |
| `pagination` | `position: 'both'` 的上下双分页 |
| `spin-debug` | `loading` 的两种形态 |

其他示例还包括 `component-token`、`pagination-simple`、`empty`、`item-extra`。
虚拟列表能力见 `Listy`；拖拽排序示例仍在能力清单中待审查。

## API

### List

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| bordered | 是否展示边框 | `boolean` | `false` |
| dataSource | 数据源 | `T[]` | — |
| extra | 列表右侧内容；窄屏移到下方，支持同名插槽 | `VNodeChild` | — |
| grid | 栅格配置（`gutter` / `column` / `xs`…`xxxl`） | `ListGridType` | — |
| id | 根元素 id | `string` | — |
| itemLayout | 列表项布局 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| loading | 加载中。⚠️ **有 `dataSource` 时渲染的是列表本身**（占位块只在数据为空时可见） | `boolean \| SpinProps` | `false` |
| loadMore | 加载更多的内容（**取代**底部分页的位置） | `VNodeChild` | — |
| pagination | 分页配置；`false` 不渲染 | `PaginationConfig \| false` | `false` |
| rowKey | 行 key（函数或字段名） | `((item: T) => string \| number) \| keyof T` | — |
| size | 尺寸。`'large'` / `'small'` 落 `-lg` / `-sm`；`'default'` 不落类 | `'small' \| 'default' \| 'large'` | — |
| split | 列表项之间是否显示分割线 | `boolean` | `true` |
| header | 列表头部 | `VNodeChild` | — |
| footer | 列表底部 | `VNodeChild` | — |
| locale | 空态文案覆盖（**纯 prop**） | `{ emptyText: VNodeChild }` | — |
| prefixCls | 类名前缀 | | — |
| class / style | **根元素原生 attrs**（不是 Props） | | — |

### List 插槽

| 插槽 | 参数 | 说明 |
|---|---|---|
| default | — | 手动编排内容；存在时不显示默认空态 |
| item | `{ item: T, index: number }` | 渲染当前页的每项；`T` 从 `dataSource` 推断，`index` 从当前页的 0 开始；不传则不渲染数据项 |
| extra | — | 列表右侧内容；窄屏移到下方 |
| header | — | 列表头部 |
| footer | — | 列表底部 |
| loadMore | — | 替换底部分页，顶部的分页仍保留 |

`header` / `footer` / `loadMore` / `extra` 按插槽是否存在决定优先级；空插槽也压住同名 prop，且不生成空头尾容器。`loadMore` 大小写需保持一致。简单内容仍可通过同名 prop 传入。
`renderItem` 已直接移除，迁移见 [List 插槽迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/list-slots.md)。

```vue
<List :data-source="users" row-key="id">
  <template #item="{ item, index }">
    <ListItem>{{ index + 1 }}. {{ item.name }}</ListItem>
  </template>
  <template #footer>共 {{ users.length }} 人</template>
</List>
```


分页配置中的 `current` / `pageSize` 分别决定是否受控；不传时使用首次启用分页时的默认值。外部更新不触发业务回调；移除控制沿用最后一次接收的值，未接受的切页请求不会污染内部状态。数据缩短时非受控页码向可用页收敛，恢复数据不跳回旧页。显式 `total` 支持服务端分页，本地数据不足一个偏移量时保留服务端返回的当前页。`align` 原样传给 Pagination，默认 `end`；`position` 仅决定 List 布局。

栅格选择当前已匹配且配置过的最大断点，未匹配时使用 `column`。根 `prefixCls` 通过最近的 List/Item 上下文传递给子组件，子组件可显式覆盖；自定义前缀的静态 CSS 生成遵循全库前缀策略。嵌套 List 的尺寸、分隔、布局和边框各自独立。原生 `dir` 优先于 Provider 方向。

### List.Item

| 参数 | 说明 | 类型 |
|---|---|---|
| actions | 操作区。每项一个 `<li>`，项间有分隔线。⚠️ **空数组不渲染** | `VNodeChild[]` |
| extra | 额外内容；横向和竖向均有稳定的 `-item-extra` 语义容器 | `VNodeChild` |
| classNames | 语义化类名（`actions` / `extra`） | `{ actions?: string; extra?: string }` |
| styles | 语义化样式（同上） | `{ actions?: CSSProperties; extra?: CSSProperties }` |
| colStyle | 用户配置的 grid `Col` 根样式，不改变 List 的列数 | `CSSProperties` |

### List.Item 插槽

| 插槽 | 说明 |
|---|---|
| default | 列表项主体 |
| extra | 额外内容；两种布局都位于稳定的 extra 容器 |
| actions | 操作项模板；数组和 Fragment 展开，每个非空顶层节点一个操作项，项间自动分隔 |

具名插槽存在即优先于同名 prop，空插槽不回退。actions 忽略注释和纯空白，`v-for` 请提供稳定 key；同一包装元素内的多个按钮视作一个操作项。`actions` prop 的既有数组数据形态保留，同样过滤空内容并保留 VNode key；数字 `0` 可显示。

### List.Item.Meta

| 参数 | 说明 | 类型 |
|---|---|---|
| avatar | 头像 | `VNodeChild` |
| title | 标题（渲染成 `<h4>`） | `VNodeChild` |
| description | 描述 | `VNodeChild` |

### List.Item.Meta 插槽

`#avatar`、`#title`、`#description` 均无作用域参数，存在时优先于同名内容 prop（含空内容）。空头像不生成头像容器，空标题不生成 `h4`；标题和描述都为空时不生成 content 容器。`0` 是可显示内容。动态内容随渲染更新。

### 实例方法（ref）

三个组件都暴露 `{ nativeElement }`（可空）：List / Meta 为 `HTMLDivElement`；Item 非 grid 时为 `HTMLLIElement`，grid 时为 `HTMLDivElement`。

## Theme

### Component Token（11 个）

| token | 说明 | 默认值 |
|---|---|---|
| `contentWidth` | 内容宽度 | `220` |
| `itemPadding` / `itemPaddingSM` / `itemPaddingLG` | 列表项内间距（三档） | `${paddingContentVertical} 0` / `${paddingContentVerticalSM} ${paddingContentHorizontal}` / `${paddingContentVerticalLG} ${paddingContentHorizontalLG}` |
| `headerBg` / `footerBg` | 头部 / 底部背景色 | `transparent` |
| `emptyTextPadding` | 空文本内边距 | `padding` |
| `metaMarginBottom` | `Meta` 下间距 | `padding` |
| `avatarMarginRight` | 头像右间距 | `padding` |
| `titleMarginBottom` | 标题下间距 | `paddingSM` |
| `descriptionFontSize` | 描述文字大小 | `fontSize` |

运行时通过 `ConfigProvider` 的 `theme.components.List` 配置上述 11 项，支持更新、移除和恢复；也可在 List 根元素使用 CSS 变量覆盖：`--apollo-list-item-padding` / `--apollo-list-content-width` 等
（11 个）。数据容器继承根变量；根原生 style 优先于 Provider 配置。

`itemPadding` 的显式覆盖在带边框默认行中也完整生效；不覆盖时，带边框行保留当前主题的标准缩进。`loading.fullscreen` 只把遮罩铺满视口，正文、输入状态与 ref 留在文档流中；通过 `loading.classNames.mask` / `loading.styles.mask` 定制实际遮罩。

分页内容使用 `#paginationItemRender="{ page, type, element }"`、`#paginationTotal="{ total, range }"` 和 `#paginationSizeChanger="info"`。每个分页器接收当前作用域，支持顶部/底部及动态插槽；配置对象只放数据和业务事件，旧 itemRender/showTotal/sizeChangerRender 函数入口已移除。


## 基本 (basic)

基础列表。`List.Item.Meta` 承载头像 / 标题 / 描述三段。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `basic` demo。
import { Avatar, List, ListItem, ListItemMeta } from '@apollo-design/ui';

const data = [
  { title: 'Ant Design Title 1' },
  { title: 'Ant Design Title 2' },
  { title: 'Ant Design Title 3' },
  { title: 'Ant Design Title 4' },
];
</script>

<template>
  <List item-layout="horizontal" :data-source="data">
    <template #item="{ item }">
      <ListItem>
        <ListItemMeta description="Ant Design, a design language for background applications.">
          <template #avatar>
            <Avatar>{{ item.title.slice(-1) }}</Avatar>
          </template>
          <template #title><a href="#demo-basic">{{ item.title }}</a></template>
        </ListItemMeta>
      </ListItem>
    </template>
  </List>
</template>
```

## 简单列表 (simple)

三档尺寸（默认 / small / large），带页头、页脚与边框。

### simple.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `simple` demo。
import { Divider, List, ListItem, Text } from '@apollo-design/ui';

const data = [
  'Racing car sprays burning fuel into crowd.',
  'Japanese princess to wed commoner.',
  'Australian walks 100km after outback crash.',
  'Man charged over missing wedding girl.',
  'Los Angeles battles huge wildfires.',
];

const sizes = [undefined, 'small', 'large'] as const;
</script>

<template>
  <template v-for="size in sizes" :key="size ?? 'default'">
    <Divider title-placement="start">
      {{ size === undefined ? 'Default' : size === 'small' ? 'Small' : 'Large' }} Size
    </Divider>
    <List :size="size" bordered :data-source="data">
      <template #header><div>Header</div></template>
      <template #footer><div>Footer</div></template>
      <template #item="{ item }">
        <ListItem><template v-if="size === undefined"><Text mark>[ITEM]</Text> </template>{{ item }}</ListItem>
      </template>
    </List>
  </template>
</template>
```

## 竖排列表样式 (vertical)

`itemLayout="vertical"` + `extra` 的两段式布局，配合 `actions` 与分页。

### vertical.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `vertical` demo。
import { Avatar, List, ListItem, ListItemMeta, Space } from '@apollo-design/ui';

const data = Array.from({ length: 6 }).map((_, i) => ({
  href: '#demo-vertical',
  title: `ant design part ${i}`,
  description: 'Ant Design, a design language for background applications.',
  content:
    'We supply a series of design principles, practical patterns and high quality design resources.',
}));
</script>

<template>
  <List
    item-layout="vertical"
    size="large"
    :pagination="{ pageSize: 3 }"
    :data-source="data"
  >
    <template #item="{ item }">
      <ListItem>
        <ListItemMeta :description="item.description">
          <template #avatar>
            <Avatar>{{ item.title.slice(-1) }}</Avatar>
          </template>
          <template #title><a :href="item.href">{{ item.title }}</a></template>
        </ListItemMeta>
        {{ item.content }}
        <template #actions>
          <Space v-for="(count, index) in ['156', '156', '2']" :key="index">
            <span style="display: inline-block; width: 1em; height: 1em; background: #999" />
            {{ count }}
          </Space>
        </template>
        <template #extra>
          <span style="display: inline-block; width: 272px; max-width: 100%; height: 120px; background: #eee" />
        </template>
      </ListItem>
    </template>
    <template #footer>
      <div><b>ant design</b> footer part</div>
    </template>
  </List>
</template>
```

## 栅格列表 (grid)

`grid` 把列表排成栅格；`column` 控制列数，`gutter` 控制间距。

### grid.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `grid` demo。
import { Card, List, ListItem } from '@apollo-design/ui';

const data = Array.from({ length: 6 }).map((_, i) => ({ title: `Title ${i + 1}` }));
</script>

<template>
  <List :grid="{ gutter: 16, xs: 1, sm: 2, lg: 3 }" :data-source="data">
    <template #item="{ item }">
      <ListItem><Card :title="item.title">Card content</Card></ListItem>
    </template>
  </List>
</template>
```

## 响应式栅格列表 (responsive)

`grid` 的每个断点键（`xs` / `sm` / `md` / `lg` / `xl` / `xxl`）可以给不同的列数。

### responsive.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `responsive` demo。
import { Card, List, ListItem } from '@apollo-design/ui';

const data = Array.from({ length: 8 }).map((_, i) => ({ title: `Title ${i + 1}` }));
</script>

<template>
  <List :grid="{ gutter: 16, xs: 1, sm: 2, md: 4, lg: 4, xl: 6, xxl: 3 }" :data-source="data">
    <template #item="{ item }">
      <ListItem><Card :title="item.title">Card content</Card></ListItem>
    </template>
  </List>
</template>
```

## 加载更多 (loadmore)

用 `#loadMore` 插槽放「加载更多」按钮 —— 它会取代底部分页的位置。

### loadmore.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `loadmore` demo。
import { Button, List, ListItem } from '@apollo-design/ui';
import { computed, onScopeDispose, ref } from 'vue';

const ALL = [
  'Racing car sprays burning fuel into crowd.',
  'Japanese princess to wed commoner.',
  'Australian walks 100km after outback crash.',
  'Man charged over missing wedding girl.',
  'Los Angeles battles huge wildfires.',
];

const loading = ref(false);
const count = ref(2);
const data = computed(() => ALL.slice(0, count.value));
let pending: ReturnType<typeof setTimeout> | undefined;
onScopeDispose(() => clearTimeout(pending));

const loadMore = () => {
  if (loading.value || count.value >= ALL.length) return;
  loading.value = true;
  // ⚠️ 上游 demo 用 `setTimeout` 模拟请求；这里保留同样的形态（固定 500ms，可复现）
  pending = setTimeout(() => {
    count.value = Math.min(count.value + 2, ALL.length);
    loading.value = false;
  }, 500);
};
</script>

<template>
  <List :loading="loading" :data-source="data">
    <template #item="{ item }"><ListItem>{{ item }}</ListItem></template>
    <template #loadMore>
      <div style="text-align: center; margin-top: 12px">
        <Button v-if="data.length < ALL.length" :loading="loading" @click="loadMore">
          loading more
        </Button>
        <span v-else>没有更多了</span>
      </div>
    </template>
  </List>
</template>
```

## 分页列表 (pagination)

`pagination` 的 `position` 可以是 `top` / `bottom` / `both`。

### pagination.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `pagination` demo。
import { List, ListItem } from '@apollo-design/ui';

const data = Array.from({ length: 12 }).map((_, i) => `item ${i + 1}`);
</script>

<template>
  <List :pagination="{ pageSize: 3, position: 'both' }" :data-source="data">
    <template #item="{ item }"><ListItem>{{ item }}</ListItem></template>
  </List>
</template>
```

## 加载中 (spin-debug)

`loading` 为 `true` 或 `{ spinning }`。⚠️ **有 `dataSource` 时渲染的是列表本身**，53px 占位块只在数据为空时可见。

### spin-debug.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `spin-debug` demo。
import { List, ListItem } from '@apollo-design/ui';

const data = ['content', 'content', 'content'];
</script>

<template>
  <List loading :data-source="data">
    <template #item="{ item }"><ListItem>{{ item }}</ListItem></template>
  </List>
</template>
```

## 组件 Token (component-token)

通过 `ConfigProvider` 的 `theme.components.List` 覆盖 `itemPadding`、`headerBg`、`footerBg`、`descriptionFontSize` 等 Component Token。

### component-token.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `component-token` demo：通过 ConfigProvider 覆盖 List 的 Component Token。
import { Avatar, Button, ConfigProvider, List, ListItem, ListItemMeta } from '@apollo-design/ui';
import { ref } from 'vue';

const themed = ref(true);

const data = Array.from({ length: 3 }, (_, i) => ({
  title: `Ant Design Title ${i + 1}`,
  description: 'Ant Design, a design language for background applications.',
}));
</script>

<template>
  <Button style="margin-bottom: 12px" @click="themed = !themed">切换 List 主题</Button>
  <ConfigProvider
    :theme="themed ? {
      components: {
        List: {
          itemPadding: '20px 24px',
          itemPaddingLG: '24px 24px',
          headerBg: '#e6f4ff',
          footerBg: '#fffbe6',
          descriptionFontSize: 16,
        },
      },
    } : undefined"
  >
    <List
      bordered
      size="large"
      :data-source="data"
    >
      <template #header><span :style="themed ? { color: '#1f1f1f' } : undefined">Component token header</span></template>
      <template #footer><span :style="themed ? { color: '#1f1f1f' } : undefined">Component token footer</span></template>
      <template #item="{ item }">
        <ListItem>
          <ListItemMeta :title="item.title" :description="item.description">
            <template #avatar><Avatar style="background-color: #1677ff; color: #000">{{ item.title.slice(0, 1) }}</Avatar></template>
          </ListItemMeta>
        </ListItem>
      </template>
    </List>
  </ConfigProvider>
</template>
```

## 简洁分页 (pagination-simple)

`pagination` 传入 `simple: true`，总数使用原生 `#paginationTotal`，列表按 `pageSize` 自动切片。

### pagination-simple.vue

```vue
<script setup lang="ts">
// Simple pagination with native total content.
import type { PaginationConfig } from '@apollo-design/ui';
import { List, ListItem, Text } from '@apollo-design/ui';

const data = Array.from({ length: 23 }, (_, i) => `Item ${i + 1}`);

const pagination: PaginationConfig = {
  pageSize: 5,
  simple: true,
};
</script>

<template>
  <div>
    <Text type="secondary">`simple` 分页可输入页码，切换后列表切片同步更新。</Text>
    <List :data-source="data" :pagination="pagination" style="margin-top: 12px">
      <template #paginationTotal="{ total, range }">{{ range[0] }}-{{ range[1] }} / {{ total }}</template>
      <template #item="{ item }"><ListItem>{{ item }}</ListItem></template>
    </List>
  </div>
</template>
```

## 列表项布局与额外内容 (item-extra)

横向布局下 `List.Item` 的 `extra` 渲染在右侧，`actions` 内的 `Button` 可交互更新点赞数。

### item-extra.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `itemLayout` / `extra` 用法：横向布局下 extra 位于右侧。
import { LikeOutlined } from '@apollo-design/icons';
import { Avatar, Button, List, ListItem, ListItemMeta, Text } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const articles = ref([
  {
    title: 'Ant Design Title 1',
    description: 'Ant Design, a design language for background applications.',
    likes: 12,
  },
  {
    title: 'Ant Design Title 2',
    description: 'We supply a series of design principles and practical patterns.',
    likes: 8,
  },
  {
    title: 'Ant Design Title 3',
    description: 'Neque porro quisquam est qui dolorem ipsum quia dolor sit amet.',
    likes: 21,
  },
]);

const totalLikes = computed(() => articles.value.reduce((sum, item) => sum + item.likes, 0));
</script>

<template>
  <div>
    <Text>
      横向 `itemLayout` 的 `extra` 位于右侧；点击 Like 会即时更新，当前总点赞：{{ totalLikes }}
    </Text>
    <List :data-source="articles" style="margin-top: 12px">
      <template #extra><Text>列表总点赞：{{ totalLikes }}</Text></template>
      <template #item="{ item: article }">
        <ListItem>
          <ListItemMeta :title="article.title" :description="article.description">
            <template #avatar>
              <Avatar style="background-color: #1677ff; color: #000">{{ article.title.slice(0, 1) }}</Avatar>
            </template>
          </ListItemMeta>
          <template #extra>
            <span style="display: inline-block; width: 120px; height: 64px; border-radius: 8px; background: linear-gradient(135deg, #1677ff 0%, #69b1ff 100%)" />
          </template>
          <template #actions>
            <Button type="link" size="small" @click="article.likes += 1"><LikeOutlined /> {{ article.likes }}</Button>
          </template>
        </ListItem>
      </template>
    </List>
  </div>
</template>
```

## 自定义空态 (empty)

`dataSource` 为空时使用 `locale.emptyText` 自定义空态，并用 `Switch` 切换数据。

### empty.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `empty` 用法：dataSource 为空时用 locale.emptyText 自定义空态。
import type { ListLocale } from '@apollo-design/ui';
import { Empty, List, ListItem, Switch, Text } from '@apollo-design/ui';
import { computed, h, ref } from 'vue';

const showData = ref(false);

const data = computed(() => (showData.value ? ['Ant Design', 'Apollo Design', 'Vue 3'] : []));

const locale = computed<ListLocale>(() => ({
  emptyText: h(Empty, {
    description: showData.value ? 'No data' : '打开开关加载数据',
  }),
}));
</script>

<template>
  <div>
    <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 12px">
      <Text>显示数据</Text>
      <Switch v-model:checked="showData" aria-label="显示列表数据" />
    </div>
    <List :data-source="data" :locale="locale">
      <template #item="{ item }"><ListItem>{{ item }}</ListItem></template>
    </List>
  </div>
</template>
```

---

# Listy

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/listy


数据驱动的轻量列表，支持按键聚合分组、原生吸顶和虚拟滚动。项内容可以包含原生交互元素。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/listy/demo) 的 8 个示例。

## API

`T` 为真实数据类型，可以是普通接口或原始值；`K extends string | number` 为组键类型。

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| items | 数据；未传时为空列表 | `T[]` | `[]` |
| rowKey | 稳定键字段或取键算法；字段值必须完整满足 `string \| number`，支持数字和 Symbol 字段名 | `ListyRowKey<T>` | 必填 |
| group | 按键聚合；同组数据无需连续，组按首次出现顺序展示 | `{ key: (item: T) => K }` | — |
| sticky | 组头吸顶；Raw 使用唯一原生组头，Virtual 使用固定组头 | `boolean` | — |
| virtual | 是否虚拟滚动；未传时继承当前 ConfigProvider.virtual | `boolean` | `false` |
| height | Raw 的 maxHeight；Virtual 的视口高度 | `number` | — |
| prefixCls | 组件类名前缀 | `string` | 当前 ConfigProvider 前缀 |
| classNames | 语义类名 | `Partial<Record<'root' \| 'item' \| 'groupHeader', string>>` | — |
| styles | 语义样式，使用 Vue `CSSProperties` | `ListyStyles` | — |

文字方向来自当前 ConfigProvider.direction。`class`、`style`、`data-*` 落到外层根元素，`style` 支持 Vue 原生字符串、对象和数组合并。`id`、`tabindex`、`role`、`aria-*`、键盘和焦点监听落到实际滚动容器：Raw 为根元素，Virtual 为 holder。控件身份与 ARIA 目标保持一致，不在外壳重复设置；视口高度由 `height` 控制。

### 插槽

| 名称 | 对象作用域 | 说明 |
|---|---|---|
| default | `{ item: T, index: number }` | 项内容；index 始终为原始 items 下标 |
| groupHeader | `{ groupKey: K, items: T[], sticky: boolean, fixed: boolean }` | 全组共享模板；未提供时显示组键，包含 `0` 和空字符串 |

槽支持 `0`、空内容、多根数组和条件切换。Raw 的唯一组头在开启吸顶时 `sticky=true, fixed=false`；Virtual 普通组头为 `false,false`，固定副本为 `false,true`。相同项键在 Raw 的替换、排序与跨组移动中保留真实节点、编辑状态和焦点；Virtual 在项持续位于已挂载窗口内时同样复用，离开窗口的项正常卸载。

### 事件

| 名称 | 参数 | 说明 |
|---|---|---|
| scroll | `(event: Event)` | 真实滚动容器的原生事件，每次通知一次；`event.target` 是实际 holder |

组件不构造合成事件，也不接管方向键、IME 或用户 `preventDefault`；原生滚动键和槽内控件保留浏览器行为。

### Ref

`ListyRef<K>` 只公开 `scrollTo(config?: ListyScrollToConfig<K>): void`。

- `number`：设置本列表的 scrollTop。
- `{ key, align?, offset? }`：定位项键。`align` 为 `'top' | 'bottom' | 'auto'`，默认 `'auto'`；顶部定位会为当前吸顶组头让位。
- `{ groupKey: K, align?, offset? }`：定位组头。
- `{ left?, top? }`：本列表的绝对滚动坐标。
- `null` / `undefined`：不指定新目标。

Raw 只修改自己的 holder，不调用会滚动外层页面的 `scrollIntoView`。Virtual 使用已有虚拟列表的测量和滚动迭代。数据键 `1` 与 `'1'`、项键与组键分别编码；`data-key` 为内部定位标识，不应自行解析。

## 主题

当前 Provider 的 Listy 配置与两个 Component Token 都响应式消费：`itemPaddingBlock`（默认 `paddingSM`）与 `itemPaddingInline`（默认 `padding`），接受数字或 CSS 长度字符串。组件覆盖可动态撤回。

Virtual 的初始估算为当前 `fontHeight + itemPaddingBlock * 2`；数字与 px 长度直接参与估算，其他 CSS 单位先采用当前 paddingSM，实际尺寸由已有 VirtualList 测量修正。未新增虚拟列表缓存或测量机制。

## 迁移

`itemRender(item,index)` 改为 `#default="{ item, index }"`；`group.title(groupKey,items)` 改为 `#groupHeader="{ groupKey, items }"`。`group.key` 继续承担数据分组职责。旧模板函数入口已移除。


## 基本 (basic)

数据驱动渲染：`items` + `row-key` + default 插槽渲染项内容。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic 用法（items 数据驱动）
import { Listy } from '@apollo-design/ui';

const items = Array.from({ length: 8 }, (_, i) => ({ key: i, content: `Item ${i}` }));
</script>

<template>
  <Listy :items="items" row-key="key">
    <template #default="{ item }">{{ item.content }}</template>
  </Listy>
</template>
```

## 分组 + 吸顶 (group)

`group.key` 聚合（不要求同组数据连续），`group.title` 渲染组头；`sticky` 让组头吸附在滚动容器顶部。

### group.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 group + sticky 用法
import { Listy } from '@apollo-design/ui';

const items = Array.from({ length: 12 }, (_, i) => ({
  key: i,
  group: `Group ${i % 3}`,
  content: `Item ${i}`,
}));

const group = {
  key: (item: (typeof items)[number]) => item.group,
};
</script>

<template>
  <Listy :items="items" row-key="key" :group="group" sticky :height="280">
    <template #groupHeader="{ groupKey, items: groupItems }">{{ groupKey }} ({{ groupItems.length }})</template>
    <template #default="{ item }">{{ item.content }}</template>
  </Listy>
</template>
```

## 虚拟滚动 (virtual)

`virtual` + `height` + 估算行高（由 token 推导）启用虚拟滚动，只渲染视口内的项。

### virtual.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 virtual 用法
import { Listy } from '@apollo-design/ui';

const items = Array.from({ length: 1000 }, (_, i) => ({ key: i, content: `Item ${i}` }));
</script>

<template>
  <Listy :items="items" row-key="key" virtual :height="280">
    <template #default="{ item }">{{ item.content }}</template>
  </Listy>
</template>
```

## 滚动定位 (scroll-to)

`ref.scrollTo(config)`：数字（scrollTop）/ `{ key, align, offset }`（按项）/ `{ groupKey }`（按组）/ `{ left, top }`。

### scroll-to.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 scrollTo 用法
import { Button, Listy, type ListyRef, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const items = Array.from({ length: 100 }, (_, i) => ({ key: i, content: `Item ${i}` }));
const listyRef = ref<ListyRef>();
</script>

<template>
  <div>
    <Space wrap style="margin-bottom: 12px">
      <Button @click="listyRef?.scrollTo(0)">到顶部</Button>
      <Button @click="listyRef?.scrollTo({ key: 80, align: 'top' })">
        滚到 Item 80
      </Button>
    </Space>
    <Listy ref="listyRef" :items="items" row-key="key" :height="240">
      <template #default="{ item }">{{ item.content }}</template>
    </Listy>
  </div>
</template>
```

## 语义化样式 (style-class)

通过 `classNames` 与 `styles` 定制 `root` / `item` / `groupHeader` 语义槽，开关可切换 item 高亮。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `style-class` 用法：Listy 的 root / item / groupHeader 语义槽。
import type { ListyClassNames, ListyStyles } from '@apollo-design/ui';
import { Listy, Switch, Text } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const highlight = ref(true);

const items = Array.from({ length: 8 }, (_, i) => ({ key: i, content: `Item ${i + 1}` }));

const classNames: ListyClassNames = {
  root: 'demo-listy-style-root',
  item: 'demo-listy-style-item',
};

const styles = computed<ListyStyles>(() =>
  highlight.value
    ? { item: { background: 'var(--apollo-color-primary-bg)', borderRadius: '6px' } }
    : {},
);
</script>

<template>
  <div>
    <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 12px">
      <Text>高亮 item 语义槽</Text>
      <Switch v-model:checked="highlight" aria-label="高亮语义槽" />
    </div>
    <Listy :items="items" row-key="key" :class-names="classNames" :styles="styles" :height="240">
      <template #default="{ item }">{{ item.content }}</template>
    </Listy>
  </div>
</template>

<style>
.demo-listy-style-root {
  padding: 4px;
  border: 1px solid var(--apollo-color-border-secondary);
  border-radius: 8px;
}

.demo-listy-style-item {
  padding: 4px 8px;
}
</style>
```

## 富内容 (rich)

在默认插槽中组合 `Avatar`、`Tag`、`Text` 与 `Button`，操作按钮可即时切换关注状态。

### rich.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `rich` 用法：头像、标题、标签与操作按钮组成富内容列表项。
import { Avatar, Button, Listy, Tag, Text } from '@apollo-design/ui';
import { ref } from 'vue';

const items = ref([
  {
    key: 1,
    name: 'Olivia',
    role: 'Product designer',
    tags: ['Design', 'Vue'],
    followed: true,
  },
  {
    key: 2,
    name: 'Liam',
    role: 'Frontend engineer',
    tags: ['TypeScript', 'Ant Design'],
    followed: false,
  },
  {
    key: 3,
    name: 'Emma',
    role: 'Design systems',
    tags: ['Tokens', 'Accessibility'],
    followed: false,
  },
  {
    key: 4,
    name: 'Noah',
    role: 'Data visualization',
    tags: ['Charts', 'SVG'],
    followed: true,
  },
]);

const toggleFollow = (item: (typeof items.value)[number]) => {
  item.followed = !item.followed;
};
</script>

<template>
  <Listy :items="items" row-key="key" :height="300">
    <template #default="{ item }">
      <div style="display: flex; align-items: center; gap: 12px; width: 100%">
        <Avatar style="background-color: #1677ff; color: #000">{{ item.name.slice(0, 1) }}</Avatar>
        <div style="flex: 1; min-width: 0">
          <Text strong>{{ item.name }}</Text>
          <div><Text type="secondary" style="font-size: 12px">{{ item.role }}</Text></div>
          <Tag v-for="tag in item.tags" :key="tag" color="blue">{{ tag }}</Tag>
        </div>
        <Button
          size="small"
          :type="item.followed ? 'default' : 'primary'"
          @click="toggleFollow(item)"
        >
          {{ item.followed ? '已关注' : '关注' }}
        </Button>
      </div>
    </template>
  </Listy>
</template>
```

## 作用域插槽 (item-render)

使用 `#default="{ item, index }"` 渲染可交互行，通过原生 `@scroll` 反馈滚动位置，并用公开 `scrollTo` 定位。

### item-render.vue

```vue
<script setup lang="ts">
// Scoped item content and the real native scroll notification.
import type { ListyRef } from '@apollo-design/ui';
import { Button, Listy, Text } from '@apollo-design/ui';
import { ref } from 'vue';

const items = ref(
  Array.from({ length: 60 }, (_, i) => ({ key: i, content: `Item ${i + 1}`, done: i % 4 === 0 })),
);

const listyRef = ref<ListyRef>();
const scrollTop = ref(0);

const onScroll = (event: Event) => {
  if (event.target instanceof HTMLElement) scrollTop.value = Math.round(event.target.scrollTop);
};
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 12px; margin-bottom: 12px">
      <Button size="small" @click="listyRef?.scrollTo({ key: 40, align: 'top' })">
        滚动到 Item 40
      </Button>
      <Text type="secondary">scrollTop: {{ scrollTop }}px</Text>
    </div>
    <Listy
      ref="listyRef"
      :items="items"
      row-key="key"
      :height="240"
      @scroll="onScroll"
    >
      <template #default="{ item, index }">
        <div style="display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 12px">
          <Text :delete="item.done">{{ index + 1 }}. {{ item.content }}</Text>
          <Button size="small" :type="item.done ? 'default' : 'primary'" @click="item.done = !item.done">
            {{ item.done ? 'Undo' : 'Done' }}
          </Button>
        </div>
      </template>
    </Listy>
  </div>
</template>
```

## 自定义分组头 (group-header)

`group.title` 返回带 `Tag` 的 VNode 组头，结合 `sticky` 吸顶与 `scrollTo({ groupKey })` 跳转分组。

### group-header.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `group` 用法：VNode 组头 + 吸顶 + 按 groupKey 滚动。
import type { ListyRef } from '@apollo-design/ui';
import { Button, Listy, Tag, Text } from '@apollo-design/ui';
import { ref } from 'vue';

const groupNames = ['Group A', 'Group B', 'Group C'];

const items = Array.from({ length: 36 }, (_, i) => ({
  key: i,
  group: groupNames[i % groupNames.length] ?? 'Group A',
  content: `Item ${i + 1}`,
}));

const listyRef = ref<ListyRef>();

const group = { key: (item: (typeof items)[number]) => item.group };

const scrollToGroup = (key: string) => {
  listyRef.value?.scrollTo({ groupKey: key, align: 'top' });
};
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 12px">
      <Button v-for="name in groupNames" :key="name" size="small" @click="scrollToGroup(name)">
        {{ name }}
      </Button>
    </div>
    <Listy ref="listyRef" :items="items" row-key="key" :group="group" sticky :height="280">
      <template #groupHeader="{ groupKey, items: groupItems }">
        <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px">
          <Tag color="blue">{{ groupKey }}</Tag>
          <Text type="secondary">{{ groupItems.length }} items</Text>
        </div>
      </template>
      <template #default="{ item }">{{ item.content }}</template>
    </Listy>
  </div>
</template>
```

---

# Masonry

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/masonry


瀑布流布局：条目按「当前最矮的一列」依次落位，高度**实测**而非预设。

## 何时使用

- 内容高度参差不齐，但希望整体视觉上「填满」容器（图片墙、卡片流、商品列表）。
- 需要按断点控制列数与间距。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/masonry/demo)（6 个，覆盖 antd 的主要用户场景）。

| demo | 内容 |
|---|---|
| `basic` | 基本（4 列 + `gutter` 16） |
| `responsive` | 列数与间距都按断点配置 |
| `dynamic` | 增删条目 + `onLayoutChange` 把列号写回 `items` |
| `fresh` | 条目内容高度会变时用 `fresh`（每个条目各挂 `ResizeObserver`） |
| `image` | 条目是图片（加载后高度才确定） |
| `style-class` | `classNames` / `styles` 的对象与函数两种形态 |

## API

### Props

| 参数 | 说明 | 类型 | 默认值 | 全局配置 |
|---|---|---|---|---|
| items | 数据源。每项 `{ key, data, column?, height?, children? }` | `MasonryItemType<T>[]` | — | × |
| columns | 列数。对象形态按断点解析（从大到小取第一个已配置的断点；都没命中 ⇒ `columns.xs ?? 1`） | `number \| Partial<Record<Breakpoint, number>>` | `3` | × |
| gutter | 间距。复用 Grid 的 `Gutter`（数字 / 字符串 / 断点对象 / `[水平, 纵向]`） | `Gutter` | `0` | × |
| fresh | 为**每个条目**各挂一个 `ResizeObserver`（内容高度会变时用）。⚠️ **不改变 DOM 结构** | `boolean` | `false` | × |
| onLayoutChange | `layoutChange` 的 Vue 事件监听器；当前条目全部完成测量后接收 **`{...item, column}`** | `(sortInfo: MasonryLayoutItem<T>[]) => void` | — | × |
| classNames | 语义化类名（`root` / `item`），支持函数形态 | `MasonrySemanticClassNames \| ((info) => …)` | — | ✅（`masonry.classNames`） |
| styles | 语义化样式（`root` / `item`），支持函数形态 | `MasonrySemanticStyles \| ((info) => …)` | — | ✅（`masonry.styles`） |
| prefixCls | 类名前缀 | `string` | 从 ConfigProvider 取，兜底 `apollo-masonry` | × |
| class / style | **根元素原生 attrs**（不是 Props）；调用方样式覆盖同名语义样式及计算得到的容器高度 | Vue class/style 绑定 | — | × |

`gutter` 数字按像素处理；CSS 字符串如 `['2rem', 'calc(0.5rem + 4px)']`、`var()` 和百分比保留 CSS 单位。横向百分比以容器宽度为基准；纵向百分比以当前条目零间距排布的高度为基准，提供显式根高度时优先使用该高度，避免间距与根高相互反馈。局部隐藏测量节点观察字体、视口和 CSS 变量变化，双轴均切回数字或组件卸载时释放。

#### MasonryItemType

| 字段 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| key | 唯一标识（数字会内部 `String()` 化） | `string \| number` | — |
| data | 业务数据，泛型 T 由 items 推导并传给 #item | `T` | — |
| column | 指定落在第几列（0 基）。超界会夹到最后一列 | `number` | 自动选最矮列 |
| height | 传给 #item 和 layoutChange 的可选元数据，不设置实测布局高度 | `number` | — |
| children | 未提供 #item 时使用的回退内容 | `VNodeChild` | — |

### Events

| 名称 | 说明 | 参数 |
|---|---|---|
| layoutChange | 完整实测布局变化。原生 Vue 监听器（包括 `.once`）接收同一个事件，事件发布不依赖 `onLayoutChange` prop | `(sortInfo: MasonryLayoutItem<T>[])` |

### Ref

| 名称 | 类型 | 说明 |
|---|---|---|
| nativeElement | `() => HTMLDivElement \| null` | 当前根元素；卸载后返回 null |

开发版 API 修正（`0.0.0`）：`MasonryRef` 现与 `MasonryExpose` 一致，使用 `masonryRef.value?.nativeElement()` 获取根元素；旧 `MasonryRef.nativeElement` 的直接元素类型与已文档化的 getter 不符。本次直接修正，无兼容层或弃用期。

### Slots

| 名称 | 参数 | 说明 |
|---|---|---|
| item | `MasonryItemSlotProps<T>`：`{ key, data, index, column, children?, height? }` | 当前条目；优先于 item.children，空槽也覆盖回退内容 |

column 为当前测量列号，首次测量前暂为 0。条件插槽、同 key 替换数据（包括响应式数组原地替换条目对象）和语义样式函数均读取当前输入；组件更新后会重测量。CSS 过渡或后代独立尺寸变化可用 fresh 持续观察。泛型也传给 layoutChange。旧 itemRender prop 已移除，见[迁移说明](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/masonry-slots.md)。

## Theme

### Component Token

Masonry **没有 Component Token**（与 antd 逐字一致：`ComponentToken` 是空接口）。
它只消费全局 alias：

| token | 用在哪 |
|---|---|
| `motionDurationSlow` | 条目淡入（`-fade-appear`）与位置过渡 |
| `motionDurationFast` | 条目淡出（`-fade-leave`） |
| `motionEaseOut` | 上述三条的缓动 |

## 设计说明

- **排布算法**：按 `items` 顺序，每项落到**当前累计高度最小**的那一列（平局取**最左**）；
  容器高度 = 最高列 − 一个纵向间距。详见 `hooks/positions.ts` 的文件头（含三处易错点）。
- **SSR 直接输出内容**：初始 items 与 #item 在服务端渲染；测量前采用正常网格流和自然高度，客户端挂载后按实际高度切换为瀑布流定位。网格按行排列，测量后才采用最短列算法。水合保留条目、输入节点和输入值，不再复制 React effect 的空首屏。
- **高度是实测的**：`item.height` 从不被读；首帧量测在 Vue 更新 DOM 之后。
- **图片事件参与测量**：根节点以原生捕获监听 load/error；非冒泡的 img 事件也会触发去抖量测与重排，fresh=false 同样有效。一般内容的尺寸变化仍可用 fresh 的逐项 ResizeObserver。
- **本组件零 ARIA**：容器与条目都是普通 `div`（无 `role`、无 `tabindex`）——
  语义由 #item 内容和调用方的原生 attrs 提供。
- **原生 attrs 透传**：id/title/事件以及字符串、对象、数组 class/style 按 Vue 规则路由到根节点。attrs 在 render 期读取，调用方 style 覆盖同名语义 root 样式，更新不替换根 DOM。默认不添加 role/ARIA，调用方可通过原生 attrs 提供必要语义。


## 基本 (basic)

瀑布流布局：条目按「当前最矮的一列」依次落位。

⚠️ antd 的 demo 用 `Card` 渲染条目，本仓 Card 尚未落地 ⇒ 用**原生 div + 等价内联样式**替换。

### basic.vue

```vue
<script setup lang="ts">
// 用不同高度的原生内容块展示瀑布流的排列。
import { Masonry } from '@apollo-design/ui';

const tileStyle = {
  padding: '8px',
  background: 'var(--apollo-color-bg-container)',
  color: 'var(--apollo-color-text)',
  border: '1px solid var(--apollo-color-border-secondary)',
  borderRadius: '8px',
  boxSizing: 'border-box',
} as const;

const heights = [150, 50, 90, 70, 110, 150, 130, 80, 50, 90, 100, 150, 60, 50, 80];

const items = heights.map((height, index) => ({ key: `item-${index}`, data: height }));
</script>

<template>
  <Masonry :columns="4" :gutter="16" :items="items">
    <template #item="{ data, index }">
      <div :style="{ height: `${data}px`, ...tileStyle }">{{ index + 1 }}</div>
    </template>
  </Masonry>
</template>
```

## 响应式 (responsive)

列数与间距都支持按断点配置 —— 命中规则是「从大到小取第一个已配置的断点」。

### responsive.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 responsive demo：列数与间距都按断点给。
import { Masonry } from '@apollo-design/ui';

const tileStyle = {
  padding: '8px',
  background: 'var(--apollo-color-bg-container)',
  color: 'var(--apollo-color-text)',
  border: '1px solid var(--apollo-color-border-secondary)',
  borderRadius: '8px',
  boxSizing: 'border-box',
} as const;

const heights = [120, 55, 85, 160, 95, 140, 75, 110, 65, 130, 90, 145, 55, 100, 80];

const items = heights.map((height, index) => ({ key: `item-${index}`, data: height }));
</script>

<template>
  <Masonry
    :columns="{ xs: 1, sm: 2, md: 3, lg: 4 }"
    :gutter="{ xs: 8, sm: 12, md: 16 }"
    :items="items"
  >
    <template #item="{ data, index }">
      <div :style="{ height: `${data}px`, ...tileStyle }">{{ index + 1 }}</div>
    </template>
  </Masonry>
</template>
```

## 动态 (dynamic)

增删条目；`onLayoutChange` 把算出来的列号写回 `items`，写回后条目就「钉」在该列。

⚠️ 与 antd 的 demo 有两处**有意**差异：① 新增条目的高度用确定值
（上游用 `Math.random()`，每次渲染都不同 ⇒ demo 冒烟测试不可复现）；
② `Card` / `CloseOutlined` 用原生 div / 文本 `×` 替换（本仓 Card 尚未落地）。

### dynamic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 dynamic demo：增删条目 + 用 `onLayoutChange` 把算出来的列号写回 items
// （写回之后条目就「钉」在该列，后续不再被自动重排）。
import { Button, Masonry, type MasonryLayoutItem } from '@apollo-design/ui';
import { ref } from 'vue';

const tileStyle = {
  padding: '8px',
  background: 'var(--apollo-color-bg-container)',
  color: 'var(--apollo-color-text)',
  border: '1px solid var(--apollo-color-border-secondary)',
  borderRadius: '8px',
  boxSizing: 'border-box',
} as const;

const heights = [150, 50, 90, 70, 110, 150, 130, 80, 50, 90, 100, 150, 70, 50, 80];

interface Item {
  key: number;
  column?: number;
  data: number;
}

const items = ref<Item[]>(
  heights.map((height, index) => ({ key: index, column: index % 4, data: height })),
);

const removeItem = (removeKey: number): void => {
  items.value = items.value.filter(({ key }) => key !== removeKey);
};

const addItem = (): void => {
  const last = items.value[items.value.length - 1];
  items.value = [
    ...items.value,
    // ⚠️ antd 的 demo 用 `Math.random()` 取高度 —— 那会让每次渲染不同。
    // 这里用**确定值**（按当前长度推导）以便 demo 冒烟测试可复现。
    { key: last ? last.key + 1 : 0, data: 50 + ((items.value.length * 17) % 100) },
  ];
};

const onLayoutChange = (sortedItems: MasonryLayoutItem<number>[]): void => {
  items.value = items.value.map((item) => {
    const match = sortedItems.find((sorted) => sorted.key === item.key);
    return match ? { ...item, column: match.column } : item;
  });
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Masonry :columns="4" :gutter="16" :items="items" @layout-change="onLayoutChange">
      <template #item="{ data, key }">
        <div :style="{ ...tileStyle, height: `${data}px`, position: 'relative' }">
          {{ Number(key) + 1 }}
          <Button
            size="small"
            :aria-label="`Remove item ${Number(key) + 1}`"
            style="position: absolute; top: 8px; right: 8px"
            @click="removeItem(Number(key))"
          >×</Button>
        </div>
      </template>
    </Masonry>
    <Button block @click="addItem">Add Item</Button>
  </div>
</template>
```

## 内容变化 (fresh)

条目内容高度会变时用 `fresh` —— 它给**每个条目**各挂一个 `ResizeObserver`，
点一下就重新量测并重排。

⚠️ `fresh` **不改变 DOM 结构**（观察器不产节点，上游的 `ResizeObserver` 是 `cloneElement`）。
与 antd 的 demo 的差异：高度用确定值而不是 `Math.random()`。

### fresh.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 fresh demo：条目内容的高度会变 ⇒ 需要 `fresh`（每个条目各挂一个
// ResizeObserver）。`fresh` 还会持续观察 CSS 过渡期间的高度变化。
import { Button, Masonry } from '@apollo-design/ui';
import { ref } from 'vue';

const tileStyle = {
  padding: '8px',
  background: 'var(--apollo-color-bg-container)',
  color: 'var(--apollo-color-text)',
  border: '1px solid var(--apollo-color-border-secondary)',
  borderRadius: '8px',
  boxSizing: 'border-box',
} as const;

const heights = [150, 50, 90, 70, 110, 150, 130, 80, 50, 90, 100, 150, 60, 50, 80];

const items = heights.map((height, index) => ({ key: `item-${index}`, data: height }));
const current = ref<number[]>([...heights]);

/** ⚠️ antd 的 demo 用 `Math.random()` —— 这里用**确定值**（每次点：换到下一档）。 */
const bump = (index: number): void => {
  current.value = current.value.map((height, i) => (i === index ? (height % 180) + 20 : height));
};
</script>

<template>
  <Masonry fresh :columns="{ xs: 2, sm: 3, lg: 4 }" :gutter="16" :items="items">
    <template #item="{ index }">
      <Button :style="{ height: `${current[index]}px`, width: '100%', ...tileStyle, whiteSpace: 'normal', transition: 'height 0.3s' }" @click="bump(index)">{{ index + 1 }} - Click</Button>
    </template>
  </Masonry>
</template>
```

## 图片 (image)

使用不同宽高比的本地 SVG 图片；图片原生 load 事件触发重新布局，不依赖外部图片服务。

Local SVG images have different aspect ratios. Their native load events trigger layout updates without an external image service.

### image.vue

```vue
<script setup lang="ts">
// Native image load events trigger a new layout; local SVG sources keep the preview available offline.
import { Masonry } from '@apollo-design/ui';

const sizes = [260, 420, 320, 480, 360, 280];
const colors = ['#91caff', '#b7eb8f', '#ffd591', '#d3adf7', '#87e8de', '#ffadd2'];
const items = sizes.map((height, index) => ({
  key: `image-${index}`,
  data: `data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="640" height="${height}" viewBox="0 0 640 ${height}"><rect width="640" height="${height}" fill="${colors[index]}"/><circle cx="480" cy="80" r="36" fill="#fff" opacity=".8"/><path d="M0 ${height}V${height * 0.7}L180 ${height * 0.3}L360 ${height * 0.8}L480 ${height * 0.5}L640 ${height * 0.85}V${height}Z" fill="#16304b" opacity=".65"/></svg>`)}`,
}));
</script>

<template>
  <Masonry :columns="{ xs: 2, sm: 3, lg: 4 }" :gutter="16" :items="items">
    <template #item="{ data, index }">
      <img :alt="`Landscape illustration ${index + 1}`" :src="data" style="width: 100%; display: block; border-radius: var(--apollo-border-radius)" />
    </template>
  </Masonry>
</template>
```

## 自定义样式 (style-class)

`classNames` / `styles` 两个语义槽都支持**对象**与**函数**两种形态；
函数形态的入参 `props.columns` 是**解析后的列数**（不是原始 prop）。

`styles` 使用原生 CSS 值：`height`、`padding`、`borderRadius` 等非零长度需显式单位，
如 `'260px'`、`'20px'`、`'12px'`；`opacity` 等无单位属性仍可用数字。
这与 `gutter` 等组件尺寸参数的数字像素约定不同。显式根高度会覆盖测量高度，须能容纳所有卡片。

`styles` uses native CSS values. Give nonzero lengths such as height, padding and border radius explicit units;
unitless properties such as opacity may remain numeric. An explicit root height overrides the measured height and must contain every tile.

⚠️ 与 antd 的 demo 的差异：上游用 `antd-style` 的 `createStaticStyles` 生成类名，
本仓没有这个依赖 ⇒ 用普通类名替换；`Flex` / `Divider` / `Typography` 换成原生元素。
**缺口登记在 `README.md` §7。**

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo：`classNames` / `styles` 两个语义槽，
// 且**对象形态与函数形态都演示一遍**。
//
// ⚠️ antd 的 demo 用 `antd-style` 的 `createStaticStyles` 生成 CSS 类 ——
// 本仓没有这个依赖 ⇒ 用**普通类名**替换（真正的样式在 `styles` 里给），
// 示例内容使用普通块元素，样式保持在当前示例内。
import { Masonry, type MasonryProps } from '@apollo-design/ui';

const heights = [120, 80, 100, 60, 140, 90, 110, 70];

const items = heights.map((height, index) => ({ key: `item-${index}`, data: height }));

/** 对象形态。 */
const styles: MasonryProps<number>['styles'] = {
  root: {
    borderRadius: '12px',
    padding: '20px',
    height: '260px',
    backgroundColor: 'var(--apollo-color-fill-alter)',
  },
  item: {
    border: '1px solid var(--apollo-color-border)',
    borderRadius: '12px',
    overflow: 'hidden',
  },
};

/** 函数形态：入参的 `props.columns` 是**解析后的列数**。 */
const stylesFn: MasonryProps<number>['styles'] = ({ props }) => ({
  root: {
    border: `2px solid ${typeof props.columns === 'number' && props.columns > 2 ? '#1890ff' : '#52c41a'}`,
    padding: '20px',
    height: '280px',
    backgroundColor: 'var(--apollo-color-primary-bg)',
  },
  item: { border: '1px solid #1890ff', borderRadius: '12px', overflow: 'hidden' },
});

const classNames = { root: 'masonry-demo-root', item: 'masonry-demo-item' };

const base = { items, columns: 4, gutter: 16 } as const;
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 24px">
    <section>
      <h4 style="margin: 0 0 8px">classNames + styles（对象）</h4>
      <Masonry v-bind="base" :class-names="classNames" :styles="styles">
        <template #item="{ data, index }">
          <div :style="{ height: `${data}px`, display: 'flex', alignItems: 'center', justifyContent: 'center', background: 'var(--apollo-color-bg-container)', color: 'var(--apollo-color-text)' }">
            {{ index + 1 }}
          </div>
        </template>
      </Masonry>
    </section>
    <section>
      <h4 style="margin: 0 0 8px">styles（函数式，按解析后的 columns 分支）</h4>
      <Masonry v-bind="base" :class-names="classNames" :styles="stylesFn">
        <template #item="{ data, index }">
          <div :style="{ height: `${data}px`, display: 'flex', alignItems: 'center', justifyContent: 'center', background: 'var(--apollo-color-bg-container)', color: 'var(--apollo-color-text)' }">
            {{ index + 1 }}
          </div>
        </template>
      </Masonry>
    </section>
  </div>
</template>
```

---

# Mentions

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/mentions


用于在输入中提及某人或某事，常用于发布、聊天或评论框。

## 何时使用

- 需要在文本输入里「@ 某个人 / # 某个标签」并弹出候选。
- 候选可能来自**异步**接口（配 `loading` + `onSearch`）。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/mentions/demo)（16 个，覆盖 antd 的主要用户场景）。

| demo | 内容 |
|---|---|
| `basic` | 基本（`options` 数据驱动） |
| `prefix` | 多触发字符（`['@', '#']`）+ `onSearch` 切换数据源 |
| `autoSize` | 高度自适应 |
| `autosize-textarea-debug` | `style.resize` 的两种取值 |
| `allowClear` | 清除按钮（默认 / 自定义图标 / 多行） |
| `async` | 异步候选（`loading` + `onSearch`） |
| `placement` | 向上展开 |
| `readonly` | `disabled` 与 `readOnly` |
| `size` | `large` / 默认 / `small` |
| `status` | `error` / `warning` |
| `variant` | `outlined` / `filled` / `borderless` / `underlined` |
| `form` | 与 `Form` 配合（受控 + 校验） |
| `popupRender` | 自定义下拉面板 |
| `style-class` | `classNames` / `styles` 的对象与函数形态 |
| `component-token` | Component Token 调试（`dropdownHeight` 等） |
| `render-panel` | 静态面板（调试用，勿在生产使用） |

## API

### Props

| 参数 | 说明 | 类型 | 默认值 | 全局配置 |
|---|---|---|---|---|
| value | 受控值（配 `v-model:value`） | `string` | — | × |
| defaultValue | 非受控初始值 | `string` | — | × |
| options | 候选项（数据驱动） | `MentionsOptionProps[]` | — | × |
| prefix | 触发字符，可传数组 | `string \| string[]` | `'@'` | × |
| split | 分词符（同时是「搜索串是否合法」的默认判据） | `string` | `' '` | × |
| filterOption | 候选过滤。传 `false` 表示**不做过滤** | `false \| ((input, option) => boolean)` | 按 `option.value` 包含输入串（大小写不敏感） | × |
| validateSearch | 搜索串是否合法 | `(text, split) => boolean` | 不含 `split` | × |
| notFoundContent | 无候选时的内容 | `VNodeChild` | `renderEmpty('Select')` | ✅（`mentions.notFoundContent`） |
| loading | 候选加载中（面板显示 Spin，且 **Enter 不选中**） | `boolean` | `false` | × |
| silent | 显式静默，Enter 不选中；独立于 loading，loading 时始终禁止选择 | `boolean` | `false` | × |
| placement | 浮层方位 | `'top' \| 'bottom'` | `'bottom'` | × |
| getPopupContainer | 浮层挂载点；挂载前可返回 null | `() => HTMLElement \| null` | — | ✅ |
| popupClassName | 浮层额外类名 | `string` | — | × |
| size | 尺寸 | `'large' \| 'middle' \| 'small'` | 从 ConfigProvider 取 | ✅ |
| disabled | 禁用 | `boolean` | 从 `DisabledContext` 取 | ✅ |
| readOnly | 只读；禁止清空与候选编辑 | `boolean` | `false` | × |
| hidden | 隐藏整个组件根元素 | `boolean` | `false` | × |
| status | 校验状态 | `'error' \| 'warning'` | 从 `Form.Item` 取 | ✅ |
| variant | 形态 | `'outlined' \| 'filled' \| 'borderless' \| 'underlined'` | `'outlined'` | ✅ |
| allowClear | 清除按钮 | `boolean \| { clearIcon?, disabled? }` | `false` | ✅（`mentions.allowClear`） |
| rows | 文本框行数 | `number` | `1` | × |
| autoSize | 高度自适应 | `boolean \| { minRows?, maxRows? }` | — | × |
| maxLength | 最大长度 | `number` | — | × |
| placeholder | 占位文本（**同时是可访问名**） | `string` | — | × |
| classNames | 语义化类名（`root` / `textarea` / `popup` / `suffix`），支持函数形态 | `MentionsSemanticClassNames \| ((info) => …)` | — | ✅（`mentions.classNames`） |
| styles | 语义化样式（同上 4 键），支持函数形态 | `MentionsSemanticStyles \| ((info) => …)` | — | ✅（`mentions.styles`） |
| prefixCls | 类名前缀 | `string` | 从 ConfigProvider 取，兜底 `apollo-mentions` | × |
| class / style | **根节点原生 attrs**（替代上游 `className` / `rootClassName` / `style`） | `string \| array \| object` / `StyleValue` | — | × |

原生 class/style 在裸形态、allowClear 及 Form 反馈三种形态中都落到最外层根。style 支持字符串、对象、混合数组和 CSS 变量，优先于 styles.root，移除后恢复语义值；id/ARIA/tabindex 继续属于 textarea。样式与 silent/loading 的当前值更新不会重挂编辑器。组件配置的 style 参与根样式合并；textarea、popup、suffix 语义样式作用于对应区域。ConfigProvider 的当前 getPopupContainer 生效，组件显式指定时优先。

受控更新是请求：父级未接受的输入或清空不会成为撤控后的本地值；移除 value 后保留最后接受值，后续输入转为本地更新。切为 disabled/readOnly 会结束普通候选交互，只读时不允许清空。

#### MentionsOptionProps

| 字段 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 选中后回填的值 | `string` | — |
| label | 展示内容 | `VNodeChild` | — |
| disabled | 不可选（键盘 ↑/↓ 会跳过） | `boolean` | `false` |
| className | 该项的类名 | `string` | — |
| style | 该项的内联样式 | `CSSProperties` | — |
| key | 只用于 `data-menu-id` | `string \| number` | `value` |

### Events

| 名称 | 说明 | 参数 |
|---|---|---|
| input | 原生文本输入 | `(event: Event)` |
| focus / blur | 文本框焦点变化；blur 按浮层焦点协调延后发送 | `(event: FocusEvent)` |
| keydown / keyup | 文本框键盘事件，支持 Vue 修饰符 | `(event: KeyboardEvent)` |
| clear | 点击清空后发送，无参数 | `()` |
| update:value | 值变化（配 `v-model:value`） | `(value: string)` |
| change | 值变化（**收字符串，不是事件**） | `(value: string)` |
| select | 选中候选项 | `(option: MentionsOptionProps, prefix: string)` |
| search | 搜索串变化（异步加载的入口） | `(text: string, prefix: string)` |
| popupScroll | 浮层滚动 | `(event: Event)` |
| pressEnter | 按下 Enter 且**不在**候选态 | `(e: KeyboardEvent)` |
| resize | 尺寸变化（`autoSize` 时） | `({ width, height })` |

`change` / `select` / `search` 使用 typed emits，支持 `@change.once` 等 Vue 监听语法及当前监听器数组；一次原生 input 只发送一次值更新。原生 DOM change/select 不触发这些语义事件。旧 `:on-search="handler"` 等函数 prop 绑定改为 `@search="handler"`；渲染函数的 `onSearch` 是标准 Vue 监听器注册。见 [迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/mentions-core-events.md)。

其他公开事件也通过 typed emits 发送，支持监听器数组、替换和 `.once`。`@keydown.stop.prevent` 等修饰符作用于原生事件；`@press-enter` 仅在非候选态发送。组件卸载会取消待处理 blur，浮层内部焦点协调不伪造 FocusEvent。旧 `:on-press-enter` / `:on-popup-scroll` / `:on-resize` 函数 prop 直接改为 `@press-enter` / `@popup-scroll` / `@resize`，见 [迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/mentions-native-events.md)。

候选键盘使用标准 `KeyboardEvent.key`：↑/↓ 跳过禁用项，Enter 单次选择，Escape 关闭；这些键的 keyup 不重复搜索或重开。IME `isComposing` 期间方向键和 Enter 留给输入法，仍向公开键盘监听器发送原始事件。手动构造键盘事件时请提供 `key`，不再依赖废弃的 `which`。见 [标准键盘迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/mentions-keyboard.md)。

### Slots

| 名称 | 说明 | 参数 |
|---|---|---|
| default | `Mentions.Option` 形式的候选项（**已 deprecated**，用 `options`） | — |
| notFoundContent | 无候选时的当前内容；存在且为空也抑制回退 | — |
| popupRender | 自定义浮层；槽存在则使用其内容，空槽不恢复默认菜单 | `{ originNode: VNode }` |

`MentionsSlots` / `MentionsPopupRenderSlotProps` 已导出并接入组件。槽按当前 render 沿包装与引擎转发；条件移除后恢复菜单，保留 textarea 节点、当前值、焦点及默认菜单的选择行为。旧 popupRender 函数 prop 已直接移除，无兼容层，见 [迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/mentions-popup-slot.md)。

空内容优先级为 `#notFoundContent`（含有意为空）→ `notFoundContent` prop → `ConfigProvider.components.mentions.notFoundContent` → `renderEmpty('Select')` → 默认空状态。插槽只在实际空菜单 render 时调用，关闭/SSR、已有候选或 loading 不提前执行；存在时不调用回退渲染函数。移除后恢复当前回退数据。`false` 保持空白，`0`、VNode 及数组按 Vue 内容规则渲染，不增加额外包装元素。

### Expose（模板 ref）

| 名称 | 说明 | 类型 |
|---|---|---|
| focus | 聚焦 | `() => void` |
| blur | 失焦 | `() => void` |
| textarea | 当前原生 `<textarea>` | `HTMLTextAreaElement \| null` |
| nativeElement | 根元素 | `HTMLElement \| null` |

### 静态成员

| 名称 | 说明 |
|---|---|
| `Mentions.Option` | @deprecated，用 `options`（也可用具名导出 `MentionsOption`） |
| `Mentions.getMentions(value, config?)` | **纯函数**：解析文本里的提及实体 |
| `Mentions._InternalPanelDoNotUseOrYouWillBeFired` | 静态面板（调试/文档用） |

`InstanceType<typeof Mentions>` 与 `MentionsRef` 均提供实际方法和元素类型。已弃用的 `Mentions.Option` 仍读取当前默认插槽，支持模板 v-for、原生 class/style 及 string/number key；未被消费的 `OptionProps.children` 已移除，内容直接写入默认插槽。`options[].label` 继续接收 VNodeChild 数据。

内部静态面板在 value 含触发前缀时展示真实候选菜单；菜单挂在自身容器内并参与布局，卸载时释放。普通 Mentions 不增加 open prop。

### Component Token

当前主题的全局别名和 21 个有效组件字段同时作用于根与 Teleport 浮层；嵌套覆盖、替换和撤除会更新现有节点。语义样式及原生根 style 继续优先。

- 长度字段（number 自动转 px，也可用 CSS 长度字符串）：lineWidthFocus、paddingBlock/SM/LG、paddingInline/SM/LG、inputFontSize/SM/LG、dropdownHeight、controlItemWidth、itemPaddingVertical。
- 字符串字段：activeBorderColor、hoverBorderColor、activeShadow、errorActiveShadow、warningActiveShadow、hoverBg、activeBg。
- 层级字段：zIndexPopup；显式 styles.popup.zIndex 优先，保留 CSS 字符串。

数值与纯数字字符串会同步到后代浮层的数值层级。顶层使用当前 zIndexPopup，嵌套时按父层级递增；显式 styles.popup.zIndex（含 0）始终优先。`var(...)`、`calc(...)`、`auto` 等 CSS 表达式保留原样，但不参与自动数值层级计算；依赖这类表达式的后代浮层层级集成仍延期，不能视为已验证。

删除没有 CSS 消费点的 addonBg；不提供无效字段兼容通道。其余字段按当前主题派生默认值，再接受 components.Mentions 覆盖。

## 键盘与无障碍

焦点**始终留在 textarea**（候选列表只是展示，`role="menu"` + `role="menuitem"`）：

| 键 | 行为 |
|---|---|
| ↑ / ↓ | 移动高亮（**跳过 `disabled` 的项**，环形） |
| Enter | 选中当前高亮项并回填（`silent` 时不选中） |
| Esc | 关闭候选面板 |

⚠️ 文本框的可访问名由**使用方**提供（`placeholder` / `aria-label` / `Form.Item` 的 label），
与 antd 一致 —— 组件猜不出「这段文本在说什么」。

## 设计指引

- 候选超过 10 条时建议配 `onSearch` 做异步过滤（`async` demo）。
- `split` 是「一个提及的结束符」：默认空格 ⇒ `@afc163 hello` 里 `afc163` 是一个完整提及。
- 回填时会在前缀前补一个 `split`（若前文没有），并去掉与候选重复的开头。


## allowClear (allowClear)

自定义清除按钮。

### allowClear.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/allowClear.tsx
// ⚠️ demo 级替换：antd 用 `@ant-design/icons` 的 `CloseSquareFilled`；本仓
//    `@apollo-design/icons` 在**视觉层用例**里解析不到（用例只链接 theme+ui）⇒
//    用等价的字符画占位（见 README §5）。
import { Mentions } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('hello world');
</script>

<template>
  <div>
    <Mentions v-model:value="value" allow-clear />
    <br />
    <br />
    <Mentions v-model:value="value" :allow-clear="{ clearIcon: '✖' }" />
    <br />
    <br />
    <Mentions v-model:value="value" allow-clear :rows="3" />
  </div>
</template>
```

## async (async)

异步加载候选项，使用原生 `#notFoundContent` 模板显示当前搜索词。更新模板内容、令插槽有意为空，或移除插槽恢复当前 `notFoundContent` 数据；操作按钮保持编辑器焦点。匹配后可正常选择和清空。

### async.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/async.tsx
// ⚠️ demo 级替换（见 README §5）：
//    1. antd 用 `antd-style` 的 `createStyles` ⇒ 本仓改用内联 style 对象；
//    2. antd 用 `lodash/debounce` ⇒ 本仓用 setTimeout 等价实现；
//    3. antd 拉 GitHub 真实头像（外网图片会污染视觉基线）⇒ 本仓用本地 data URI；
//    4. antd 的 label 是 JSX fragment ⇒ 本仓用渲染函数 `h`（`label` 收 VNode）。
import { Button, Flex, Mentions } from '@apollo-design/ui';
import { computed, h, onBeforeUnmount, ref } from 'vue';

const AVATAR =
  'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyMCIgaGVpZ2h0PSIyMCIgdmlld0JveD0iMCAwIDIwIDIwIj48cmVjdCB3aWR0aD0iMjAiIGhlaWdodD0iMjAiIGZpbGw9IiNkOWQ5ZDkiLz48L3N2Zz4=';

const USERS = [
  { login: 'afc163', avatar: AVATAR },
  { login: 'zombieJ', avatar: AVATAR },
  { login: 'yesmeck', avatar: AVATAR },
];

const value = ref('');
const query = ref('');
const showEmpty = ref(true);
const empty = ref(false);
const revision = ref(0);
const selections = ref(0);
const fallback = computed(() => `Default empty message for ${query.value || 'all users'}`);
const loading = ref(false);
const users = ref<{ login: string; avatar: string }[]>([]);
let timer: ReturnType<typeof setTimeout> | undefined;

const onSearch = (search: string) => {
  query.value = search;
  if (timer !== undefined) {
    clearTimeout(timer);
  }
  loading.value = !!search;
  users.value = [];
  if (!search) {
    return;
  }
  timer = setTimeout(() => {
    loading.value = false;
    users.value = USERS.filter((u) => u.login.toLowerCase().includes(search.toLowerCase()));
  }, 120);
};

onBeforeUnmount(() => {
  if (timer !== undefined) {
    clearTimeout(timer);
  }
});

const options = computed(() =>
  users.value.map(({ login, avatar }) => ({
    key: login,
    value: login,
    className: 'async-option',
    label: [
      h('img', {
        class: 'async-avatar',
        draggable: false,
        src: avatar,
        title: login,
        alt: login,
        style: { width: '20px', height: '20px', marginInlineEnd: '8px' },
      }),
      h('span', null, login),
    ],
  })),
);
</script>

<template>
  <div>
    <Flex wrap gap="small" style="margin-bottom: 12px">
      <Button @mousedown.prevent @click="showEmpty = !showEmpty">Toggle custom empty message</Button>
      <Button @mousedown.prevent @click="empty = !empty">Empty custom message</Button>
      <Button @mousedown.prevent @click="revision++">Update empty message</Button>
    </Flex>
    <Mentions v-model:value="value" aria-label="Search mention users" style="width: 100%"
      :loading="loading" :options="options" :not-found-content="fallback" allow-clear
      @search="onSearch" @select="selections++">
      <template v-if="showEmpty" #notFoundContent>
        <span v-if="!empty" data-native-empty-message>No users for {{ query || 'all users' }} · {{ revision }}</span>
      </template>
    </Mentions>
    <output data-async-mention-value>{{ value }}</output>
    <output data-async-mention-selections>Selections: {{ selections }}</output>
  </div>
</template>
```

## autoSize (autoSize)

自适应内容高度。

### autoSize.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/autoSize.tsx
import { Mentions } from '@apollo-design/ui';

const options = [
  { value: 'afc163', label: 'afc163' },
  { value: 'zombieJ', label: 'zombieJ' },
  { value: 'yesmeck', label: 'yesmeck' },
];
</script>

<template>
  <Mentions auto-size style="width: 100%" :options="options" />
</template>
```

## autosize-textarea-debug (autosize-textarea-debug)

autoSize debug

### autosize-textarea-debug.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/autosize-textarea-debug.tsx
import { Flex, Mentions } from '@apollo-design/ui';

const options = [
  { value: 'afc163', label: 'afc163' },
  { value: 'zombieJ', label: 'zombieJ' },
  { value: 'yesmeck', label: 'yesmeck' },
];
</script>

<template>
  <Flex vertical :gap="32">
    <Mentions placeholder="can resize" :options="options" />
    <Mentions placeholder="disable resize" style="resize: none" :options="options" />
  </Flex>
</template>
```

## basic (basic)

基本使用。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic.tsx
import { Mentions } from '@apollo-design/ui';

const options = [
  { value: 'afc163', label: 'afc163' },
  { value: 'zombieJ', label: 'zombieJ' },
  { value: 'yesmeck', label: 'yesmeck' },
];
</script>

<template>
  <Mentions style="width: 100%" default-value="@afc163" :options="options" />
</template>
```

## component-token (component-token)

切换组件 Token，观察当前候选菜单的最大高度、最小宽度和层级。

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, Flex, Mentions } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const InternalMentions = Mentions._InternalPanelDoNotUseOrYouWillBeFired;

const compact = ref(false);
const options = Array.from({ length: 16 }, (_, index) => ({
  value: `author${index + 1}`,
  label: `Author ${index + 1}`,
}));
const theme = computed(() => ({
  components: {
    Mentions: {
      dropdownHeight: compact.value ? 120 : 500,
      controlItemWidth: compact.value ? 180 : 300,
      zIndexPopup: compact.value ? 1100 : 1000,
    },
  },
}));
</script>

<template>
  <Flex vertical gap="small">
    <Button style="align-self: flex-start" :aria-pressed="compact" @click="compact = !compact">Toggle component tokens</Button>
  <ConfigProvider :theme="theme">
    <InternalMentions style="width: 100%" value="@" :options="options" aria-label="Custom token mention preview" />
  </ConfigProvider>
  </Flex>
</template>
```

## form (form)

受控模式，例如配合 Form 使用。

### form.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/form.tsx（受控 + 校验）
// ⚠️ demo 级替换：antd 用 `Form.useForm()`；本仓用 `useForm()` + `:form`（见 form/demo/basic.vue）。
import { Button, Form, FormItem, Mentions, Space, useForm } from '@apollo-design/ui';
import { reactive } from 'vue';

const { getMentions } = Mentions;

const formState = reactive({ coders: '' });
const [formRef] = useForm();

const checkMention = async (_: unknown, value: string) => {
  const mentions = getMentions(value);
  if (mentions.length < 2) {
    throw new Error('More than one must be selected!');
  }
};

const options = [
  { value: 'afc163', label: 'afc163' },
  { value: 'zombieJ', label: 'zombieJ' },
  { value: 'yesmeck', label: 'yesmeck' },
];
</script>

<template>
  <Form
    :model="formState"
    :form="formRef"
    layout="horizontal"
    :label-col="{ xs: { span: 24 }, sm: { span: 6 } }"
    :wrapper-col="{ xs: { span: 24 }, sm: { span: 16 } }"
  >
    <FormItem name="coders" label="Top coders" :rules="[{ validator: checkMention }]">
      <Mentions v-model:value="formState.coders" :rows="1" :options="options" />
    </FormItem>
    <FormItem :wrapper-col="{ xs: { span: 24, offset: 0 }, sm: { span: 14, offset: 6 } }">
      <Space>
        <Button type="primary" html-type="submit">Submit</Button>
        <Button html-type="reset">Reset</Button>
      </Space>
    </FormItem>
  </Form>
</template>
```

## placement (placement)

向上展开建议。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/placement.tsx
import { Mentions } from '@apollo-design/ui';

const options = [
  { value: 'afc163', label: 'afc163' },
  { value: 'zombieJ', label: 'zombieJ' },
  { value: 'yesmeck', label: 'yesmeck' },
];
</script>

<template>
  <Mentions style="width: 100%" placement="top" :options="options" />
</template>
```

## popupRender (popupRender)

使用原生 `#popupRender="{ originNode }"` 包装默认菜单。输入 @ 后可切换、更新或清空槽；空槽不恢复菜单，移除槽才恢复。工具栏鼠标操作保留编辑焦点，默认菜单的键盘导航与选择继续工作。

### popupRender.vue

```vue
<script setup lang="ts">
import { Button, Divider, Flex, Mentions, type MentionsOptionProps } from '@apollo-design/ui';
import { ref } from 'vue';

const show = ref(true);
const empty = ref(false);
const revision = ref(0);
const value = ref('');
const options = ref<MentionsOptionProps[]>([
  { value: 'afc163', label: 'afc163' },
  { value: 'zombieJ', label: 'zombieJ' },
  { value: 'yesmeck', label: 'yesmeck' },
]);
const updateOptions = () => {
  options.value = options.value.map((option) => ({ ...option, label: `${option.value} updated` }));
};
</script>

<template>
  <div>
    <Flex wrap gap="small" style="margin-bottom: 12px">
      <Button @mousedown.prevent @click="show = !show">Toggle mention popup slot</Button>
      <Button @mousedown.prevent @click="empty = !empty">Empty mention popup slot</Button>
      <Button @mousedown.prevent @click="revision++">Update mention header</Button>
      <Button @mousedown.prevent @click="updateOptions">Update mention options</Button>
    </Flex>
    <Mentions v-model:value="value" aria-label="Custom mention editor" style="width: 100%" :options="options" allow-clear>
      <template v-if="show" #popupRender="{ originNode }">
        <section v-if="!empty" data-native-mentions-popup>
          <header class="native-mentions-header">Custom Header {{ revision }}</header>
          <Divider style="margin: var(--apollo-margin-xxs) 0" />
          <component :is="originNode" />
        </section>
      </template>
    </Mentions>
    <output data-mention-value>{{ value }}</output>
  </div>
</template>

<style scoped>
.native-mentions-header {
  padding: var(--apollo-padding-xs) var(--apollo-padding-sm);
  font-weight: var(--apollo-font-weight-strong);
  color: var(--apollo-color-text-description);
}
</style>
```

## prefix (prefix)

通过 `prefix` 属性自定义触发字符。默认为 `@`, 可以定义为数组。

### prefix.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/prefix.tsx
import { Mentions } from '@apollo-design/ui';
import { ref } from 'vue';

const MOCK_DATA: Record<string, string[]> = {
  '@': ['afc163', 'zombiej', 'yesmeck'],
  '#': ['1.0', '2.0', '3.0'],
};

const prefix = ref('@');

const onSearch = (_: string, newPrefix: string) => {
  prefix.value = newPrefix;
};
</script>

<template>
  <Mentions
    style="width: 100%"
    placeholder="input @ to mention people, # to mention tag"
    :prefix="['@', '#']"
    @search="onSearch"
    :options="(MOCK_DATA[prefix] ?? []).map((value) => ({ key: value, value, label: value }))"
  />
</template>
```

## readonly (readonly)

通过 `disabled` 属性设置是否生效。通过 `readOnly` 属性设置是否只读。

### readonly.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/readonly.tsx
import { Mentions } from '@apollo-design/ui';

const options = ['afc163', 'zombiej', 'yesmeck'].map((value) => ({
  value,
  key: value,
  label: value,
}));
</script>

<template>
  <div>
    <div style="margin-bottom: 10px">
      <Mentions style="width: 100%" placeholder="this is disabled Mentions" disabled :options="options" />
    </div>
    <Mentions style="width: 100%" placeholder="this is readOnly Mentions" read-only :options="options" />
  </div>
</template>
```

## render-panel (render-panel)

调试用组件，请勿直接使用。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/render-panel.tsx
import { Mentions } from '@apollo-design/ui';

const InternalMentions = Mentions._InternalPanelDoNotUseOrYouWillBeFired;

const options = [
  { value: 'afc163', label: 'afc163' },
  { value: 'zombieJ', label: 'zombieJ' },
];
</script>

<template>
  <InternalMentions style="width: 100%" value="@" :options="options" aria-label="Mention panel preview" />
</template>
```

## size (size)

通过 `size` 属性配置大小。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/size.tsx
import { Flex, Mentions } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="medium">
    <Mentions size="large" placeholder="large size" />
    <Mentions placeholder="default size" />
    <Mentions size="small" placeholder="small size" />
  </Flex>
</template>
```

## status (status)

使用 `status` 为 Mentions 添加状态。可选 `error` 或者 `warning`。

### status.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/status.tsx
import { Mentions, Space } from '@apollo-design/ui';

const options = [
  { value: 'afc163', label: 'afc163' },
  { value: 'zombieJ', label: 'zombieJ' },
  { value: 'yesmeck', label: 'yesmeck' },
];
</script>

<template>
  <Space vertical>
    <Mentions default-value="@afc163" status="error" :options="options" />
    <Mentions default-value="@afc163" status="warning" :options="options" />
  </Space>
</template>
```

## style-class (style-class)

通过 `classNames` 和 `styles` 传入对象/函数可以自定义 Mentions 的语义化结构样式，例如设置文本框可缩放。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx
// ⚠️ demo 级替换：antd 用 `antd-style` 的 `createStyles` 生成类名 ⇒ 本仓改用
//    等价的**静态类名**（`classNames`）+ 组件自带的 `styles`（见 README §5）。

import type { MentionsProps } from '@apollo-design/ui';
import { Flex, Mentions } from '@apollo-design/ui';

const options = [
  { value: 'afc163', label: 'afc163' },
  { value: 'zombieJ', label: 'zombieJ' },
  { value: 'meet-student', label: 'meet-student' },
  { value: 'thinkasany', label: 'thinkasany' },
];

/** 等值替换 antd 的 `useStyles()` 产物（`{ root: 300px 宽 + 主色边框 }`）。 */
const classNames = {
  root: 'mentions-style-class-root',
};

const stylesObject: MentionsProps['styles'] = {
  textarea: {
    fontSize: '14px',
    resize: 'vertical',
    fontWeight: 200,
  },
};

const stylesFunction: MentionsProps['styles'] = (info) => {
  if (info.props.variant === 'filled') {
    return {
      root: { border: '1px solid #722ed1' },
      popup: { border: '1px solid #722ed1' },
    };
  }
  return {};
};
</script>

<template>
  <Flex vertical gap="medium">
    <Mentions :class-names="classNames" :options="options" :styles="stylesObject" placeholder="Object" :rows="2" />
    <Mentions :options="options" :styles="stylesFunction" variant="filled" placeholder="Function" />
  </Flex>
</template>

<style scoped>
.mentions-style-class-root {
  width: 300px;
  border: 1px solid #1677ff;
  border-radius: 8px;
}
</style>
```

## variant (variant)

Mentions 形态变体，可选 `outlined` `filled` `borderless` `underlined` 四种形态。

### variant.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/variant.tsx
import { Flex, Mentions } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical :gap="12">
    <Mentions placeholder="Outlined" />
    <Mentions placeholder="Filled" variant="filled" />
    <Mentions placeholder="Borderless" variant="borderless" />
    <Mentions placeholder="Underlined" variant="underlined" />
  </Flex>
</template>
```

---

# Menu

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/menu


提供水平、垂直和内嵌导航，以 `items` 数据描述条目、子菜单、分组及分隔线。示例见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/menu/demo)。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| items | 唯一菜单内容源；数据可含 VNode 与每项图标渲染函数 | `ItemType[]` | — |
| mode / theme | 布局与亮暗主题 | `'horizontal' \| 'vertical' \| 'inline'` / `'light' \| 'dark'` | `'vertical'` / `'light'` |
| selectedKeys / defaultSelectedKeys | 受控选中 / 初始选中；支持 `v-model:selectedKeys` | `string[]` | `[]` |
| openKeys / defaultOpenKeys | 受控展开 / 初始展开；支持 `v-model:openKeys` | `string[]` | `[]` |
| activeKey | 受控活动项；撤控保留最后接收值 | `string` | — |
| selectable / multiple | 是否可选中 / 多选 | `boolean` | `true` / `false` |
| disabled | 菜单禁用；未设置时继承 ConfigProvider | `boolean` | — |
| inlineCollapsed | 折叠为图标条，未设置时跟随 Sider | `boolean` | — |
| tooltip | 折叠项的 Tooltip 配置，`false` 关闭 | `false \| TooltipProps` | — |
| inlineIndent | 内嵌层级缩进，单位 px | `number` | `24` |
| triggerSubMenuAction | 弹出子菜单触发方式；内嵌仍用点击与键盘 | `'hover' \| 'click'` | `'hover'` |
| subMenuOpenDelay / subMenuCloseDelay | 子菜单悬停延迟，单位秒 | `number` | `0.1` / `0.1` |
| forceSubMenuRender | 保留子菜单渲染 | `boolean` | `false` |
| disabledOverflow | 关闭水平溢出折叠 | `boolean` | `false` |
| getPopupContainer | 弹层容器；未设置时继承当前 ConfigProvider | `(node: HTMLElement) => HTMLElement \| ShadowRoot` | — |
| prefixCls / id / role / tabIndex | 当前前缀及根列表属性 | `string` / `string` / `string` / `number` | — / — / `'menu'` / `0` |
| classNames / styles | `root/list/item/itemTitle/itemIcon/itemContent`，嵌套 `popup.root` 与 `subMenu` | `MenuClassNames` / `MenuStyles` | — |

原生 `class`、`style`（含字符串和数组）、`data-*`、ARIA 与原生监听器落到真实根 `ul`，水平 Overflow 使用相同落点。`click` 是菜单业务事件，原生键盘监听用 `@keydown`，`h()` 用 `onKeydown`。根样式优先于 Provider 与语义样式；样式不写到隐藏的路径登记树。

### Emits

| 事件 | 载荷 |
|---|---|
| update:selectedKeys / update:openKeys | `string[]` |
| click | `MenuInfo`，包括 `key/keyPath/itemData/domEvent` |
| select / deselect | `SelectInfo`，另含 `selectedKeys`；deselect 只在多选移除时触发 |
| openChange | 当前提议的 `string[]` |

所有业务通知由 Vue emits 提供，支持监听器数组与 `.once`。`keyPath` 从当前项到根逆序排列；`domEvent` 是原生事件，可用它取消链接默认行为。父组件未接受受控提议时，随后撤控保留最后接收值。

### 数据与插槽

`items[].label/extra/icon/itemIcon` 是数据通道，`icon` 函数接收 `RenderIconInfo`。子菜单的 `expandIcon` 函数与 `onClick/onTitleClick/onTitleMouseEnter/onTitleMouseLeave` 继续属于具体数据项。子菜单可通过 `theme` 为本层及后代弹层选择主题。`type: 'submenu'` 可声明尚无子项的子菜单。

| 组件 | Slot | Scope / 内容 |
|---|---|---|
| Menu | expandIcon | `{ isOpen, isSelected, isSubMenu, disabled }`；每项数据 expandIcon 优先 |
| MenuItem | default / title / extra | 标题与附加内容；文本 title prop 仍可用 |
| MenuItem | icon | `RenderIconInfo` |
| MenuSubMenu | title / icon / expandIcon | 图标 scope 为 `RenderIconInfo` |
| MenuItemGroup | title / default | 分组标题 / 子项 |

插槽在渲染期读取，存在即优先，包含有意为空、文本及多节点。Menu 的默认插槽不是另一棵菜单声明树；保留 items 数据与路径登记的统一来源。静态子组件导出沿用此内部菜单上下文协议。

### Expose

`list: HTMLUListElement | null` 是当前真实根列表，包含水平 Overflow；`focus(options?)` 聚焦首个启用的菜单项；`findItem({ key })` 查找当前实例的实际项（包括弹出子菜单），key 可包含引号等字符。卸载后元素引用清空。

## Provider 与样式

`components.menu` 的 `className/style/classNames/styles`、全局禁用、方向和容器跟随当前配置替换及撤除。`theme.components.Menu` 当前支持公开的十个数字 Token：`dropdownWidth/zIndexPopup/radiusItem/itemBorderRadius/radiusSubMenuItem/subMenuItemBorderRadius/activeBarWidth/activeBarHeight/activeBarBorderWidth/itemMarginInline`。两个旧 radius 别名影响对应圆角，显式的现代字段优先。静态 CSS 的其他变量仍可直接定制，不代表额外组件 Token 已实现。全局 Alias 与这十个 Token 同步投影到根列表、内嵌列表和真实弹出列表；数值弹层层级同步提供给后代。非数值 CSS 层级表达式保留样式，自动数值后代层级仍属延期边界。

## 键盘与原生操作

菜单项自身获得焦点时，Enter 或 Space 激活其中唯一的原生链接或按钮；普通条目单次触发点击/选择。直接聚焦子控件时保留浏览器的激活语义。disabled 条目阻止原生导航，输入与可编辑内容保留自己的按键。菜单项中有多个操作时，应直接聚焦所需控件。

内嵌子菜单普通收起后隐藏列表；切换模式或启用 inlineCollapsed 时，离场结束后移除列表。整棵菜单初次挂载不播放入场动画。悬停计时器及待执行焦点帧在卸载时释放。

## 开发版迁移

顶层 `expandIcon` 渲染 prop 改用 `#expandIcon`，静态项图标改用 `#icon`；数据项渲染函数保留。旧 `onKeyDown` 改用原生 `onKeydown` / `@keydown`。删除从未消费的 `children` 类型字段，菜单内容继续走 `items`。业务监听仍使用 `@click/@select/@deselect/@openChange`，程序化监听保留 `onClick/onSelect/onDeselect/onOpenChange` 名称。


## 原生链接与按钮 (native-actions)

方向键移动菜单焦点，Enter 激活所属原生链接或按钮。直接聚焦子控件时保留浏览器自己的激活语义；普通菜单项也支持 Space。按钮每次仅执行一次，禁用链接不会导航。

### native-actions.vue

```vue
<script setup lang="ts">
import { type ItemType, Menu, type MenuInfo } from '@apollo-design/ui';
import { h, ref, useId } from 'vue';

const target = useId();
const actions = ref(0);
const selected = ref<string[]>([]);
const lastEvent = ref('');
const items: ItemType[] = [
  { key: 'link', label: h('a', { href: `#${target}` }, '原生链接 / Native link') },
  {
    key: 'button',
    label: h(
      'button',
      { type: 'button', onClick: () => actions.value++ },
      '原生按钮 / Native button',
    ),
  },
  {
    key: 'disabled',
    disabled: true,
    label: h('a', { href: '#disabled-menu-action' }, '禁用链接 / Disabled link'),
  },
  { key: 'plain', label: '普通菜单项 / Plain item' },
];
const record = (info: MenuInfo) => {
  lastEvent.value = `${info.key}: ${info.domEvent.type}`;
};
</script>

<template>
  <Menu v-model:selectedKeys="selected" :items="items" aria-label="Native menu actions" @click="record" />
  <p :id="target" role="status">Actions: {{ actions }} · {{ lastEvent }}</p>
</template>
```

## 自定义样式 (custom-style)

通过根元素的 `--apollo-menu-*` 组件 Token 变量调整菜单项高度、圆角、选中背景与文字颜色，并用 `styles.itemContent` 设置菜单项内容的字重。

点击菜单项可以切换选中状态。

### custom-style.vue

```vue
<script setup lang="ts">
// 自定义样式：组件 Token 变量 + `styles.itemContent` 语义槽。
import type { ItemType } from '@apollo-design/ui';
import { Menu } from '@apollo-design/ui';
import { ref } from 'vue';

const current = ref<string[]>(['1']);

const items: ItemType[] = [
  { key: '1', label: 'Dashboard' },
  { key: '2', label: 'Projects' },
  { key: '3', label: 'Settings' },
];

const menuStyle = {
  width: 'min(256px, 100%)',
  '--apollo-menu-item-height': '44px',
  '--apollo-menu-item-border-radius': '10px',
  '--apollo-menu-item-margin-inline': '0px',
  '--apollo-menu-item-selected-bg': '#f0f5ff',
  '--apollo-menu-item-selected-color': '#2f54eb',
};

const styles = {
  itemContent: { fontWeight: 500 },
};
</script>

<template>
  <div class="demo-menu-custom-style">
    <Menu
      v-model:selectedKeys="current"
      mode="inline"
      :items="items"
      :styles="styles"
      :style="menuStyle"
    />
    <p class="demo-menu-custom-style-hint">当前选中：{{ current[0] }}</p>
  </div>
</template>

<style scoped>
.demo-menu-custom-style {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

.demo-menu-custom-style-hint {
  margin: 0;
  color: var(--apollo-color-text-secondary);
}
</style>
```

## 额外内容 (extra-style)

items 的 extra 字段渲染右侧附加内容。

### extra-style.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/extra-style.tsx（items 的 extra 字段：右侧附加内容）

import type { ItemType } from '@apollo-design/ui';
import { Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const current = ref<string[]>(['1']);

const items: ItemType[] = [
  { key: '1', label: 'Option 1', extra: '⌘P' },
  { key: '2', label: 'Option 2', extra: '⌘B' },
];
</script>

<template>
  <Menu v-model:selectedKeys="current" mode="inline" :items="items" style="width: min(256px, 100%)" />
</template>
```

## 水平导航 (horizontal)

水平的顶部导航菜单。

### horizontal.vue

```vue
<script setup lang="ts">
// 对齐 antd 6.6.4 demo/horizontal.tsx：
// - 顶层只有 item / submenu / link，**没有** type:'group'（group 放在 SubMenu.children 内）
// - Navigation Two 禁用；Navigation Four 是链接

import { AppstoreOutlined, MailOutlined, SettingOutlined } from '@apollo-design/icons';
import type { ItemType } from '@apollo-design/ui';
import { Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const current = ref<string[]>(['mail']);
const items: ItemType[] = [
  { key: 'mail', label: 'Navigation One', icon: h(MailOutlined) },
  { key: 'app', label: 'Navigation Two', icon: h(AppstoreOutlined), disabled: true },
  {
    key: 'SubMenu',
    label: 'Navigation Three - Submenu',
    icon: h(SettingOutlined),
    children: [
      {
        type: 'group',
        label: 'Item 1',
        children: [
          { key: 'setting:1', label: 'Option 1' },
          { key: 'setting:2', label: 'Option 2' },
        ],
      },
      {
        type: 'group',
        label: 'Item 2',
        children: [
          { key: 'setting:3', label: 'Option 3' },
          { key: 'setting:4', label: 'Option 4' },
        ],
      },
    ],
  },
  {
    key: 'alipay',
    label: h(
      'a',
      { href: 'https://ant.design', target: '_blank', rel: 'noopener noreferrer' },
      'Navigation Four - Link',
    ),
  },
];

const handleClick = (info: { key: string }) => {
  current.value = [info.key];
};
</script>

<template>
  <Menu v-model:selectedKeys="current" mode="horizontal" :items="items" @click="handleClick" />
</template>
```

## 水平导航（暗色） (horizontal-dark)

暗色主题的水平导航菜单。

### horizontal-dark.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/horizontal-dark.tsx（暗色水平菜单）

import { AppstoreOutlined, MailOutlined } from '@apollo-design/icons';
import type { ItemType } from '@apollo-design/ui';
import { Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const current = ref<string[]>(['mail']);
const items: ItemType[] = [
  { key: 'mail', label: 'Navigation One', icon: h(MailOutlined) },
  { key: 'app', label: 'Navigation Two', icon: h(AppstoreOutlined) },
];
</script>

<template>
  <Menu v-model:selectedKeys="current" mode="horizontal" theme="dark" :items="items" />
</template>
```

## 内嵌菜单 (inline)

垂直菜单，子菜单内嵌在菜单区域。

### inline.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/inline.tsx（内嵌菜单：嵌套 submenu + group）

import { AppstoreOutlined, MailOutlined, SettingOutlined } from '@apollo-design/icons';
import type { ItemType } from '@apollo-design/ui';
import { Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const current = ref<string[]>(['1']);
const openKeys = ref<string[]>(['sub1']);
const items: ItemType[] = [
  {
    key: 'sub1',
    label: 'Navigation One',
    icon: h(MailOutlined),
    children: [
      { key: '1', label: 'Option 1' },
      { key: '2', label: 'Option 2' },
      { key: '3', label: 'Option 3' },
      { key: '4', label: 'Option 4' },
    ],
  },
  {
    key: 'sub2',
    label: 'Navigation Two',
    icon: h(AppstoreOutlined),
    children: [
      { key: '5', label: 'Option 5' },
      { key: '6', label: 'Option 6' },
      { key: '7', label: 'Option 7' },
      { key: '8', label: 'Option 8' },
    ],
  },
  {
    key: 'sub3',
    label: 'Navigation Three',
    icon: h(SettingOutlined),
    children: [
      { key: '9', label: 'Option 9' },
      { key: '10', label: 'Option 10' },
      { key: '11', label: 'Option 11' },
      { key: '12', label: 'Option 12' },
    ],
  },
];

const handleClick = (info: { key: string }) => {
  current.value = [info.key];
};
</script>

<template>
  <Menu
    v-model:selectedKeys="current"
    v-model:openKeys="openKeys"
    mode="inline"
    :items="items"
    @click="handleClick"
  />
</template>
```

## 折叠菜单 (inline-collapsed)

点击按钮折叠/展开菜单（折叠态标题走 Tooltip）。

### inline-collapsed.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/inline-collapsed.tsx（折叠态：图标条 + Tooltip 标题）

import {
  AccountBookOutlined,
  AppstoreOutlined,
  ContainerOutlined,
  MailOutlined,
} from '@apollo-design/icons';
import type { ItemType } from '@apollo-design/ui';
import { Button, Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const collapsed = ref(false);
const current = ref<string[]>(['1']);
const openKeys = ref<string[]>(['sub1']);

const items: ItemType[] = [
  {
    key: 'sub1',
    label: 'Navigation One',
    icon: h(MailOutlined),
    children: [
      { key: '1', label: 'Option 1' },
      { key: '2', label: 'Option 2' },
    ],
  },
  {
    key: 'sub2',
    label: 'Navigation Two',
    icon: h(AppstoreOutlined),
    children: [
      { key: '3', label: 'Option 3' },
      { key: '4', label: 'Option 4' },
    ],
  },
  {
    key: 'sub3',
    label: 'Navigation Three',
    icon: h(ContainerOutlined),
    children: [
      { key: '5', label: 'Option 5' },
      { key: '6', label: 'Option 6' },
    ],
  },
  {
    key: 'sub4',
    label: 'Navigation Four',
    icon: h(AccountBookOutlined),
    children: [
      { key: '7', label: 'Option 7' },
      { key: '8', label: 'Option 8' },
    ],
  },
];
</script>

<template>
  <div style="width: min(256px, 100%)">
    <Button type="primary" style="margin-bottom: 16px" @click="collapsed = !collapsed">
      {{ collapsed ? 'Expand' : 'Collapse' }}
    </Button>
    <Menu
      v-model:selectedKeys="current"
      v-model:openKeys="openKeys"
      mode="inline"
      :inline-collapsed="collapsed"
      :items="items"
    />
  </div>
</template>
```

## 与 Layout.Sider 联动 (sider-current)

与 Layout.Sider 的折叠联动。

### sider-current.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/sider-current.tsx（Layout.Sider 联动 —— v1 用 Sider 的
// collapsed(collapsed: boolean) 事件驱动 inlineCollapsed）

import { AppstoreOutlined, MailOutlined } from '@apollo-design/icons';
import type { ItemType } from '@apollo-design/ui';
import { Layout, Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const { Sider } = Layout;
const collapsed = ref(false);
const current = ref<string[]>(['1']);
const openKeys = ref<string[]>(['sub1']);

const items: ItemType[] = [
  {
    key: 'sub1',
    label: 'Navigation One',
    icon: h(MailOutlined),
    children: [
      { key: '1', label: 'Option 1' },
      { key: '2', label: 'Option 2' },
    ],
  },
  {
    key: 'sub2',
    label: 'Navigation Two',
    icon: h(AppstoreOutlined),
    children: [
      { key: '3', label: 'Option 3' },
      { key: '4', label: 'Option 4' },
    ],
  },
];
</script>

<template>
  <Layout style="min-height: 320px">
    <Sider
      collapsible
      :collapsed="collapsed"
      @collapse="(c: boolean) => (collapsed = c)"
    >
      <Menu
        v-model:selectedKeys="current"
        v-model:openKeys="openKeys"
        mode="inline"
        theme="dark"
        :inline-collapsed="collapsed"
        :items="items"
      />
    </Sider>
    <Layout.Content style="padding: 16px; min-width: 0">Toggle the sidebar to update the menu.</Layout.Content>
  </Layout>
</template>
```

## 自定义样式 (style-class)

通过 styles 定制菜单项。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx（semantic classNames/styles 对象形态）

import type { ItemType } from '@apollo-design/ui';
import { Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const current = ref<string[]>(['1']);

const items: ItemType[] = [
  { key: '1', label: 'Option 1' },
  { key: '2', label: 'Option 2' },
];

const styles = {
  item: { borderRadius: '8px' },
  itemContent: { fontWeight: 600 },
};
</script>

<template>
  <Menu
    v-model:selectedKeys="current"
    mode="inline"
    :items="items"
    :styles="styles"
    style="width: min(256px, 100%)"
  />
</template>
```

## 子菜单主题 (submenu-theme)

为子菜单设置独立的主题。

### submenu-theme.vue

```vue
<script setup lang="ts">
// 对齐 antd 6.6.4 demo/submenu-theme.tsx：
// vertical 菜单 + Switch 切换**子菜单独立主题**（items[].theme），
// 并用 getPopupContainer 把弹层挂在触发元素的父节点内。

import { MailOutlined } from '@apollo-design/icons';
import type { ItemType, MenuTheme } from '@apollo-design/ui';
import { Menu, Switch } from '@apollo-design/ui';
import { computed, h, ref } from 'vue';

const menuTheme = ref<MenuTheme>('light');
const current = ref<string[]>(['1']);
const dark = computed({
  get: () => menuTheme.value === 'dark',
  set: (value: boolean) => {
    menuTheme.value = value ? 'dark' : 'light';
  },
});

const items = computed<ItemType[]>(() => [
  {
    key: 'sub1',
    icon: h(MailOutlined),
    label: 'Navigation One',
    theme: menuTheme.value,
    children: [
      { key: '1', label: 'Option 1' },
      { key: '2', label: 'Option 2' },
      { key: '3', label: 'Option 3' },
    ],
  },
  { key: '5', label: 'Option 5' },
  { key: '6', label: 'Option 6' },
]);

const getPopupContainer = (node: HTMLElement): HTMLElement =>
  (node.parentNode as HTMLElement | null) ?? document.body;
</script>

<template>
  <Switch aria-label="Use dark submenu theme" v-model:checked="dark" checked-children="Dark" un-checked-children="Light" />
  <br />
  <br />
  <Menu
    v-model:selectedKeys="current"
    :open-keys="['sub1']"
    :items="items"
    mode="vertical"
    theme="dark"
    :get-popup-container="getPopupContainer"
    style="width: min(256px, 100%)"
  />
</template>
```

## 切换菜单类型 (switch-mode)

切换内嵌和弹出的菜单类型。

### switch-mode.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/switch-mode.tsx（Switch 切换 mode）

import { AppstoreOutlined, MailOutlined } from '@apollo-design/icons';
import type { ItemType } from '@apollo-design/ui';
import { Menu, Switch } from '@apollo-design/ui';
import { h, ref } from 'vue';

const mode = ref<'inline' | 'vertical'>('inline');
const current = ref<string[]>(['1']);
const openKeys = ref<string[]>(['sub1']);

const items: ItemType[] = [
  {
    key: 'sub1',
    label: 'Navigation One',
    icon: h(MailOutlined),
    children: [
      { key: '1', label: 'Option 1' },
      { key: '2', label: 'Option 2' },
    ],
  },
  {
    key: 'sub2',
    label: 'Navigation Two',
    icon: h(AppstoreOutlined),
    children: [
      { key: '3', label: 'Option 3' },
      { key: '4', label: 'Option 4' },
    ],
  },
];
</script>

<template>
  <div style="display: flex; gap: 12px; align-items: center; margin-bottom: 16px">
    <Switch
      :checked="mode === 'vertical'"
      aria-label="switch mode"
      @change="(checked: boolean | string | number) => (mode = checked ? 'vertical' : 'inline')"
    />
    {{ mode === 'vertical' ? 'vertical' : 'inline' }} menu
  </div>
  <Menu
    v-model:selectedKeys="current"
    v-model:openKeys="openKeys"
    :mode="mode"
    :items="items"
    style="width: min(256px, 100%)"
  />
</template>
```

## 主题 (theme)

支持两种主题：light 与 dark。

### theme.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/theme.tsx（暗色内嵌菜单）

import { AppstoreOutlined, MailOutlined, SettingOutlined } from '@apollo-design/icons';
import type { ItemType } from '@apollo-design/ui';
import { Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const current = ref<string[]>(['1']);
const openKeys = ref<string[]>(['sub1']);
const items: ItemType[] = [
  {
    key: 'sub1',
    label: 'Navigation One',
    icon: h(MailOutlined),
    children: [
      { key: '1', label: 'Option 1' },
      { key: '2', label: 'Option 2' },
      { key: '3', label: 'Option 3' },
      { key: '4', label: 'Option 4' },
    ],
  },
  {
    key: 'sub2',
    label: 'Navigation Two',
    icon: h(AppstoreOutlined),
    children: [
      { key: '5', label: 'Option 5' },
      { key: '6', label: 'Option 6' },
      { key: '7', label: 'Option 7' },
      { key: '8', label: 'Option 8' },
    ],
  },
  {
    key: 'sub3',
    label: 'Navigation Three',
    icon: h(SettingOutlined),
    children: [
      { key: '9', label: 'Option 9' },
      { key: '10', label: 'Option 10' },
      { key: '11', label: 'Option 11' },
      { key: '12', label: 'Option 12' },
    ],
  },
];
</script>

<template>
  <Menu
    v-model:selectedKeys="current"
    v-model:openKeys="openKeys"
    mode="inline"
    theme="dark"
    :items="items"
    style="width: min(256px, 100%)"
  />
</template>
```

## 折叠提示 (tooltip)

折叠后配合 Tooltip 显示菜单标题。

### tooltip.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/tooltip.tsx（折叠态 tooltip 标题 —— inline-collapsed 的tooltip 通道）

import { MailOutlined, PieChartOutlined } from '@apollo-design/icons';
import type { ItemType } from '@apollo-design/ui';
import { Button, Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const collapsed = ref(true);
const current = ref<string[]>(['1']);

const items: ItemType[] = [
  { key: '1', label: 'Option 1', icon: h(PieChartOutlined) },
  { key: '2', label: 'Option 2', icon: h(MailOutlined) },
];
</script>

<template>
  <div :style="{ width: collapsed ? '80px' : '256px', maxWidth: '100%' }">
    <Button style="margin-bottom: 16px" @click="collapsed = !collapsed">
      {{ collapsed ? 'Expand' : 'Collapse' }}
    </Button>
    <Menu
      v-model:selectedKeys="current"
      mode="inline"
      :inline-collapsed="collapsed"
      :items="items"
    />
  </div>
</template>
```

## 垂直菜单 (vertical)

子菜单是弹出的形式。

### vertical.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/vertical.tsx（垂直菜单）

import { AppstoreOutlined, MailOutlined, SettingOutlined } from '@apollo-design/icons';
import type { ItemType } from '@apollo-design/ui';
import { Menu } from '@apollo-design/ui';
import { h, ref } from 'vue';

const current = ref<string[]>(['1']);
const openKeys = ref<string[]>(['sub1']);
const items: ItemType[] = [
  {
    key: 'sub1',
    label: 'Navigation One',
    icon: h(MailOutlined),
    children: [
      { key: '1', label: 'Option 1' },
      { key: '2', label: 'Option 2' },
      { key: '3', label: 'Option 3' },
      { key: '4', label: 'Option 4' },
    ],
  },
  {
    key: 'sub2',
    label: 'Navigation Two',
    icon: h(AppstoreOutlined),
    children: [
      { key: '5', label: 'Option 5' },
      { key: '6', label: 'Option 6' },
      { key: '7', label: 'Option 7' },
      { key: '8', label: 'Option 8' },
    ],
  },
  {
    key: 'sub3',
    label: 'Navigation Three',
    icon: h(SettingOutlined),
    children: [
      { key: '9', label: 'Option 9' },
      { key: '10', label: 'Option 10' },
      { key: '11', label: 'Option 11' },
      { key: '12', label: 'Option 12' },
    ],
  },
];

const handleClick = (info: { key: string }) => {
  current.value = [info.key];
};
</script>

<template>
  <Menu
    v-model:selectedKeys="current"
    v-model:openKeys="openKeys"
    mode="vertical"
    :items="items"
    @click="handleClick"
    style="width: min(256px, 100%)"
  />
</template>
```

## component-token (component-token)

切换当前 Menu 组件 Token，菜单保持当前选中状态。公开 Token 与全局 Alias 同步投影到根列表和弹出子菜单；静态 CSS 变量继续支持样式定制。

Switch the current Menu component tokens while preserving selection. Public tokens and current global aliases reach both the root list and teleported submenus; static CSS variables remain available for styling.

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, type ItemType, Menu } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const current = ref<string[]>(['1']);
const alternate = ref(false);
const theme = computed(() => ({
  components: {
    Menu: alternate.value
      ? { itemBorderRadius: 2, activeBarWidth: 8, itemMarginInline: 2 }
      : { itemBorderRadius: 12, activeBarWidth: 4, itemMarginInline: 8 },
  },
}));
const items: ItemType[] = [
  { key: '1', label: 'Option 1' },
  { key: '2', label: 'Option 2' },
];
</script>

<template>
  <section>
    <Button style="margin-bottom: 12px" @click="alternate = !alternate">Switch Menu tokens</Button>
    <ConfigProvider :theme="theme">
      <Menu v-model:selectedKeys="current" mode="inline" :items="items" style="width: min(256px, 100%)" />
    </ConfigProvider>
  </section>
</template>
```

---

# Message

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/message


全局展示操作反馈信息。命令式 API（`message.success(...)`），浮层走 portal。

## 何时使用

- 需要在页面顶部短暂提示操作结果（成功 / 失败 / 警告 / 进行中）。
- 需要「进行中 → 完成」的连续反馈（`loading` + `then` 串联）。
- ⚠️ 优先用 `message.useMessage()` 的 `contextHolder`：静态方法**无法消费 context**，
  组件内 Provider 的配置不会注入静态实例；静态实例读取 `ConfigProvider.config()` 的全局服务。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/message/demo)（11 个，覆盖 antd 的主要用户场景）：component-token / duration / hooks /
info / loading / other / render-panel / stack / style-class / thenable / update。

## API

### 静态方法

| 方法 | 说明 | 签名 |
|---|---|---|
| `message.success` / `info` / `warning` / `error` / `loading` | 打开一条对应类型的消息 | `(content, duration?, onClose?) => MessageType` |
| `message.open` | 完整配置打开 | `(config: ArgsProps) => MessageType` |
| `message.destroy` | 关闭（传 key 关一条，不传清空） | `(key?: string \| number) => void` |
| `message.config` | 全局默认配置（**合并**语义） | `(config: ConfigOptions) => void` |
| `message.useMessage` | hooks 形态 | `(config?: ConfigOptions \| (() => ConfigOptions)) => [MessageInstance, () => VNode]` |
| `message._InternalPanelDoNotUseOrYouWillBeFired` | 私有：单条静态面板（文档/调试） | 组件 |
| `message._InternalListDoNotUseOrYouWillBeFired` | 私有：静态列表（同上） | 组件 |

> ⚠️ `success('内容', duration)` 的**第二参传函数**时它被当作 `onClose`，第三参忽略。

### 返回值 `MessageType`

**可调用 + thenable**：

```ts
const hide = message.loading('进行中…', 0);
hide();                       // 调用即关闭
message.loading('进行中…', 2).then(() => message.success('完成'));
```

| 成员 | 说明 |
|---|---|
| `()` | 关闭这条消息 |
| `.then(fn)` | 消息终止后 resolve `true`：计时关闭、调用句柄、destroy、淘汰、挂载前取消或 owner 卸载 |
| `.promise` | 底层 `Promise<boolean>` |

### `ArgsProps`（`message.open` 的入参）

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| content | 内容 | `VNodeChild` | — |
| duration | 显示时长（秒）。`0` 不自动关闭 | `number` | `3` |
| type | `'info' \| 'success' \| 'error' \| 'warning' \| 'loading'` | — | — |
| key | 唯一标识；同 key 再 open ⇒ **复用同一条**（更新内容） | `string \| number` | 自动生成 |
| icon | 自定义图标（优先于类型图标；类型类名仍叠加） | `VNodeChild` | 类型图标 |
| onClose | 自然关闭时回调 | `() => void` | — |
| onClick | 点击 notice 根 | `(e: MouseEvent) => void` | — |
| pauseOnHover | 悬停暂停计时 | `boolean` | `true` |
| className / style | notice 根的类名/样式 | — | — |
| classNames / styles | 语义化槽位（见下） | — | — |

### `ConfigOptions`（`config()` / `useMessage()`）

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| top | 距顶部偏移（number ⇒ px） | `number \| string` | `8` |
| duration | 默认时长（秒） | `number` | `3` |
| maxCount | 最多同时显示（超出保留**最后** N 条） | `number` | — |
| rtl | 列表根加 `-rtl` 类 | `boolean` | 取 ConfigProvider 方向 |
| stack | 堆叠折叠：`true` 或 `{ threshold }` | `boolean \| { threshold?: number }` | `false` |
| pauseOnHover | 悬停暂停 | `boolean` | `true` |
| getContainer | portal 容器 | `() => HTMLElement \| ShadowRoot` | `document.body` |
| prefixCls | 类名前缀 | `string` | `apollo-message` |
| transitionName | 动效名 | `string` | `{prefixCls}-fade` |
| classNames / styles | 语义化槽位 | — | — |

### 语义化槽位（6 个）

```
list / listContent        // 列表级
root / wrapper / icon / title   // 单条级
```

> ⚠️ `classNames` / `styles` 使用对象。`list` / `listContent` 只属于 holder 配置和 PureList；单条 Args 与 PurePanel 只接受单条字段。

### Slots（C8-R2，仅 `_InternalPanelDoNotUseOrYouWillBeFired` 静态面板）

| Slot | 说明 | 参数 |
|---|---|---|
| content | 富内容（文本 `content` prop 等价，slot 优先） | — |
| icon | 自定义图标（空 slot 等价隐藏） | — |

> `message.open({ content, icon })` 的命令式入参保持 `VNodeChild`（程序化上下文，无模板）。

### 类型导出

`MessageArgsProps`、`MessageConfigOptions`、`MessageInstance`、`MessageType`、
`MessageNoticeType`、`MessageTypeOpen`、`MessageJointContent`、`MessageSemanticType`。

## Theme（Component Token）

3 个（CSS 变量 `--apollo-message-*`）：`zIndexPopup`(`zIndexPopupBase + 1000 + 10` = **2010**，
注意不是 notification 的 `+50`) / `contentBg`(`colorBgElevated`) /
`contentPadding`(`(controlHeightLG − fontSize × lineHeight) / 2` px + `paddingSM` px)。

## 设计说明

### 复用了 notification 的共享样式层

antd 的 message 完全建立在 rc-notification 之上（`useRcNotification`），样式也复用
notification 的共享 token 与列表项样式。本仓同样如此：命令式 API 与浮层结构由
`notification/engine/`（rc-notification 的 Vue 自建）提供，message 只做
「配置翻译 + 图标/语义槽 + 命令式入口」。

### 命令式路径的 holder 与队列

`message.success()` 没有组件实例 ⇒ 状态挂在**模块级单例**上：首次调用建 holder
（挂到**游离 div** 上，不进 document）、把任务压进队列，实例就绪后按序回放。
`config()` 是**合并**语义并触发一次同步。

### 样式引入

```ts
import '@apollo-design/theme/dist/tokens.css'; // 主题变量，必须先引
import '@apollo-design/ui/message/style.css';  // 按需
// 或
import '@apollo-design/ui/style.css';          // 汇总
```

自定义 `prefixCls`（如 `my-app`）时用 `genMessageStyle('my-app')` 自行产出 CSS。

## FAQ

**为什么 notice 里没有关闭按钮？**

message 传的是 `closable: false`（与 antd 一致）—— 消息靠计时自动消失，
不需要关闭按钮。

**`config()` 之后已经显示的消息会跟着变吗？**

当前列表展示跟随配置更新，`maxCount` 在下一次 `open` 时执行。


Hook holder 内已打开消息的类型与图标类跟随当前 ConfigProvider 前缀，保留 keyed 正文及用户样式。显式 icon（含 null、false、0）优先于类型默认图标。手动 destroy 不触发 onClose，自然关闭保留既有回调契约。


### Vue 契约与迁移

在 setup 中调用 `useMessage`，将零参 holder factory 作为组件渲染，或调用它取得 VNode。holder 挂载前的命令按序排队。同 key 的每个返回句柄都会在终止时结算；`true` 表示终止，不表示成功展示。最新 `onClose` 仍只在自动关闭时调用，调用关闭句柄、destroy、淘汰或卸载不会额外触发它。

PurePanel 将原生 `class`、`style`、attrs 和类型化 `@click` 作用到实际宿主；旧 `className` 改用 `class`。富内容使用 `#content` / `#icon`，保留 `0` 与显式空内容。PureList 的语义样式映射改用 `styles`，原生 `style` 设置其宿主样式。

Holder 配置和 Provider 对象在渲染时读取，替换和撤除会更新已有 keyed 内容且保留用户输入节点。三个组件 Token 跟随当前主题。列表数值 z-index 覆盖（含 `0` 和数值字符串）同时提供后代 popup 使用的数值上下文；CSS 表达式保持原样，数值上下文使用当前 Token。


## component-token (component-token)

使用局部 `ConfigProvider` 动态覆盖消息的背景、内边距和层级，并与默认消息对照。移除覆盖后恢复当前站点主题。

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, Flex, message } from '@apollo-design/ui';
import { ref } from 'vue';

const InternalPanel = message._InternalPanelDoNotUseOrYouWillBeFired;
const custom = ref(true);
const theme = {
  components: {
    Message: {
      contentBg: 'var(--apollo-color-primary-bg)',
      contentPadding: '16px 24px',
      zIndexPopup: 2100,
    },
  },
};
</script>

<template>
  <Flex vertical gap="middle" align="flex-start">
    <Button @click="custom = !custom">{{ custom ? 'Use default tokens' : 'Use custom tokens' }}</Button>
    <InternalPanel content="Default message" type="info" />
    <ConfigProvider :theme="custom ? theme : undefined">
      <InternalPanel content="Message with current component tokens" type="success" />
    </ConfigProvider>
  </Flex>
</template>
```

## duration (duration)

自定义时长 `10s`，默认时长为 `3s`。

### duration.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/duration.tsx —— 自定义时长 10s（默认 3s）
import { Button, message } from '@apollo-design/ui';

const [messageApi, contextHolder] = message.useMessage();

const success = () => {
  messageApi.open({
    type: 'success',
    content: 'This is a prompt message for success, and it will disappear in 10 seconds',
    duration: 10,
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Button @click="success">Customized display duration</Button>
</template>
```

## hooks (hooks)

通过 `message.useMessage` 创建支持读取 context 的 `contextHolder`。请注意，我们推荐通过顶层注册的方式代替 `message` 静态方法，因为静态方法无法消费上下文，因而 ConfigProvider 的数据也不会生效。

### hooks.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/hooks.tsx —— 推荐形态：useMessage() 的 contextHolder 能消费 context
import { Button, message } from '@apollo-design/ui';

const [messageApi, contextHolder] = message.useMessage();

const info = () => {
  messageApi.info('Hello, Apollo Design!');
};
</script>

<template>
  <component :is="contextHolder" />
  <Button type="primary" @click="info">Display normal message</Button>
</template>
```

## info (info)

静态方法无法消费 Context，不能动态响应 ConfigProvider 提供的各项配置。请优先使用 hooks 版本或者 App 组件提供的 `message` 实例。

### info.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/info.tsx —— 静态方法（无法消费 context，推荐用 hooks 形态）
import { Button, message } from '@apollo-design/ui';
import { onBeforeUnmount, useId } from 'vue';

const key = useId();
onBeforeUnmount(() => message.destroy(key));

const info = () => {
  message.info({ key, content: 'This is a normal message' });
};
</script>

<template>
  <Button type="primary" @click="info">Static Method</Button>
</template>
```

## loading (loading)

进行全局 loading，异步自行移除。

### loading.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/loading.tsx —— 全局 loading，异步自行移除（duration: 0 不自动关）
import { Button, message } from '@apollo-design/ui';

const [messageApi, contextHolder] = message.useMessage();

const success = () => {
  messageApi.open({
    type: 'loading',
    content: 'Action in progress..',
    duration: 0,
  });
  // 手动异步移除
  setTimeout(messageApi.destroy, 2500);
};
</script>

<template>
  <component :is="contextHolder" />
  <Button @click="success">Display a loading indicator</Button>
</template>
```

## other (other)

包括成功、失败、警告。

### other.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/other.tsx —— success / error / warning 三种类型
import { Button, message, Space } from '@apollo-design/ui';

const [messageApi, contextHolder] = message.useMessage();

const success = () => {
  messageApi.open({ type: 'success', content: 'This is a success message' });
};
const error = () => {
  messageApi.open({ type: 'error', content: 'This is an error message' });
};
const warning = () => {
  messageApi.open({ type: 'warning', content: 'This is a warning message' });
};
</script>

<template>
  <component :is="contextHolder" />
  <Space wrap>
    <Button @click="success">Success</Button>
    <Button @click="error">Error</Button>
    <Button @click="warning">Warning</Button>
  </Space>
</template>
```

## render-panel (render-panel)

调试用组件，请勿直接使用。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/render-panel.tsx —— 调试用组件，请勿直接使用
import { message } from '@apollo-design/ui';

const InternalPanel = message._InternalPanelDoNotUseOrYouWillBeFired;
</script>

<template>
  <component :is="InternalPanel" content="Hello World!" type="error" />
</template>
```

## stack (stack)

堆叠配置，默认关闭。超过阈值后的消息会被自动收起，可以通过 `threshold` 设置触发堆叠的数量。折叠状态下仅展示最新的消息。

### stack.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/stack.tsx —— 堆叠配置（默认关闭；threshold 决定折叠阈值）
// ⚠️ 本仓 useMessage 接受 getter 形态的配置 ⇒ 开关与阈值改动能实时生效
import { Button, Divider, InputNumber, message, Space, Switch } from '@apollo-design/ui';
import { ref } from 'vue';

const enabled = ref(true);
const threshold = ref(3);
const index = ref(0);

const [messageApi, contextHolder] = message.useMessage(() => ({
  stack: enabled.value ? { threshold: threshold.value } : false,
}));

const openMessage = () => {
  index.value += 1;
  const isOdd = index.value % 2 === 1;
  messageApi.open({
    type: 'info',
    content: isOdd
      ? `Message ${index.value}: This is a stacked message.`
      : `Message ${index.value}: This is a slightly longer stacked message.`,
    duration: 0,
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Space wrap size="large">
    <Space wrap>
      <span>Enabled: </span>
      <Switch v-model:checked="enabled" aria-label="Enable message stack" />
    </Space>
    <Space wrap>
      <span>Threshold: </span>
      <InputNumber
        v-model:value="threshold"
        aria-label="Stack threshold"
        :disabled="!enabled"
        :step="1"
        :min="1"
        :max="10"
      />
    </Space>
  </Space>
  <Divider />
  <Space wrap>
    <Button type="primary" @click="openMessage">Open the message box</Button>
    <Button @click="messageApi.destroy()">Destroy all</Button>
  </Space>
</template>
```

## style-class (style-class)

通过 `classNames` 和 `styles` 可以自定义消息的语义化结构样式。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx —— 用 classNames / styles 自定义语义化结构样式

import type { MessageArgsProps } from '@apollo-design/ui';
import { Button, message, Space } from '@apollo-design/ui';

const defaultStyles: NonNullable<MessageArgsProps['styles']> = {
  root: {
    backgroundColor: '#f6ffed',
    border: '2px solid #95de64',
    borderRadius: 16,
    boxShadow: '4px 4px 0 #d9f7be',
  },
  icon: { color: '#237804' },
  title: { color: '#237804', fontWeight: 600 },
};

const errorStyles: NonNullable<MessageArgsProps['styles']> = {
  root: {
    backgroundColor: '#fff2f0',
    border: '2px solid #ffccc7',
    borderRadius: 16,
    boxShadow: '4px 4px 0 #ffccc7',
  },
  icon: { color: '#cf1322' },
  title: { color: '#cf1322', fontWeight: 600 },
};

const [messageApi, contextHolder] = message.useMessage();

const showObjectStyle = () => {
  messageApi.open({
    type: 'success',
    content: 'This is a message with object styles',
    styles: defaultStyles,
  });
};

const showErrorStyle = () => {
  messageApi.open({
    type: 'error',
    content: 'This is a message with error styles',
    styles: errorStyles,
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Space wrap>
    <Button @click="showObjectStyle">Object style</Button>
    <Button type="primary" @click="showErrorStyle">Error style</Button>
  </Space>
</template>
```

## thenable (thenable)

可以通过 then 接口在关闭后运行 callback。以上用例将在每个 message 将要结束时通过 then 显示新的 message。

### thenable.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/thenable.tsx —— 用 then 串联消息（关闭后 resolve true）
import { Button, message } from '@apollo-design/ui';

const [messageApi, contextHolder] = message.useMessage();

const success = () => {
  messageApi
    .open({ type: 'loading', content: 'Action in progress..', duration: 2.5 })
    .then(() => message.success('Loading finished', 2.5))
    .then(() => message.info('Loading finished', 2.5));
};
</script>

<template>
  <component :is="contextHolder" />
  <Button @click="success">Display sequential messages</Button>
</template>
```

## update (update)

可以通过唯一的 `key` 来更新内容。

### update.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/update.tsx —— 同 key 复用同一条 notice（更新内容）
import { Button, message } from '@apollo-design/ui';

const [messageApi, contextHolder] = message.useMessage();
const key = 'updatable';

const openMessage = () => {
  messageApi.open({ key, type: 'loading', content: 'Loading...' });
  setTimeout(() => {
    messageApi.open({ key, type: 'success', content: 'Loaded!', duration: 2 });
  }, 1000);
};
</script>

<template>
  <component :is="contextHolder" />
  <Button type="primary" @click="openMessage">Open the message box</Button>
</template>
```

---

# Modal

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/modal


模态对话框。用于需要用户处理事务、又不希望跳转页面导致流程中断的场景。

## 何时使用

- 需要用户**集中注意力**处理一件事（表单、确认、警告）时。
- 需要**命令式**弹出（`Modal.confirm(...)` / `Modal.info(...)`）时。
- 需要在弹窗内做焦点约束（焦点陷阱 + 关闭后归还焦点）时。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/modal/demo)（23 个，覆盖 antd 的主要用户场景）。

## API

### 组件式 `<Modal>`

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| open / v-model:open | 是否显示；取消/关闭请求 false，确定只通知 | `boolean` | `false` |
| title | 标题（同名 `#title` slot 优先） | `string` | — |
| width | 宽度（可传响应式断点对象） | `string \| number \| Partial<Record<Breakpoint, string \| number>>` | `520` |
| height | 高度 | `string \| number` | — |
| loading | 内容区骨架态（**此时 footer 强制不渲染**） | `boolean` | `false` |
| centered | 垂直居中 | `boolean` | `false` |
| closable | 关闭按钮。`false` ⇒ 不渲染；对象可给 `disabled` / `onClose` / `afterClose` | `boolean \| {...}` | `true` |
| mask | 遮罩。`false` ⇒ 无遮罩；对象可给 `enabled` / `blur` / `closable` | `boolean \| { enabled?, blur?, closable? }` | `true` |
| okText / cancelText | 按钮文案（同名 `#okText` / `#cancelText` slot 优先） | `string` | locale（OK / Cancel） |
| okType | 确定按钮类型 | `'text' \| 'link' \| 'primary' \| 'default' \| 'dashed'` | `'primary'` |
| confirmLoading | 确定按钮 loading（**为真时点取消不关**） | `boolean` | `false` |
| okButtonProps / cancelButtonProps | 确定/取消按钮属性；根类名用 Vue 原生 `class`（不是 `className` / `rootClassName`） | `ModalButtonProps` | — |
| getContainer | 容器；`false` ⇒ **内联渲染**（不 portal） | `GetContainer` (Portal; includes Element / ShadowRoot / function / false) | `document.body` |
| zIndex | 层级 | `number` | — |
| keyboard | ESC 可关 | `boolean` | `true` |
| scrollLock | 打开时锁 body 滚动 | `boolean` | `true` |
| forceRender | 没开也渲染 | `boolean` | `false` |
| destroyOnHidden | 关闭后卸载 | `boolean` | `false` |
| mousePosition | zoom 动效的原点 | `{ x, y } \| null` | — |
| focusable | 焦点行为：`{ trap?, focusTriggerAfterClose? }` | — | `trap` 跟 `mask`；`focusTriggerAfterClose: true` |
| panelRef | 面板根节点（透传给 watermark） | `Ref \| Function` | — |
| classNames / styles | 9 个语义目标；对象或接收当前 `{ props: ModalProps }` 的函数 | `ModalProps["classNames"] / ModalProps["styles"]` | — |

**deprecated（dev 告警）**：`bodyStyle` → `styles.body`；`maskStyle` → `styles.mask`；
`destroyOnClose` → `destroyOnHidden`；`focusTriggerAfterClose` → `focusable.focusTriggerAfterClose`；
`maskClosable` → `mask.closable`；`autoFocusButton` → `focusable.autoFocusButton`。

### 事件与插槽

| 事件 | 参数 | 说明 |
|---|---|---|
| `update:open` | `boolean` | 取消/关闭请求；受控父级拒绝时保持真实显示状态 |
| `ok` | `Event` | 确定通知；父级管理异步 loading 和关闭 |
| `cancel` | `Event` | 取消按钮、关闭按钮、遮罩或 Escape |
| `afterClose` | 无 | 关闭动效结束 |
| `afterOpenChange` | `boolean` | 开启/关闭动效结束 |

| 插槽 | 作用域 | 内容 |
|---|---|---|
| default | — | 正文 |
| title / okText / cancelText / closeIcon | — | 具名内容；空插槽隐藏内容 |
| footer | `{ OkBtn, CancelBtn }` | 稳定的操作组件，消费当前按钮配置和事件 |
| modalRender | `{ ModalPanel }` | 稳定的当前面板组件；通过 `<component :is="ModalPanel" />` 包装 |

原生 `class`、`style`、`id`、ARIA、data 属性及监听落到实际面板。
`panelRef` 接收 `HTMLElement | null`；组件不承诺 focus/blur 方法。
未传 `open` 时初始关闭；撤销受控后保留最后一次接收的值，不泄漏被父级拒绝的提议。

### 命令式（静态方法）

| 方法 | 说明 |
|---|---|
| `Modal.confirm(config)` / `info` / `success` / `error` / `warning` / `warn` | 弹出一个确认框。`warning` 与 `warn` **是同一个函数** |
| `Modal.destroyAll()` | 关闭全部命令式实例 |
| `Modal.useModal()` | 返回 `[api, contextHolder]`，`api` 有同样 6 个方法 |
| `Modal.config({ rootPrefixCls })` | **已废弃**，请用 `ConfigProvider.config` |
| `Modal._InternalPanelDoNotUseOrYouWillBeFired` | 私有静态面板（**不 portal、不遮罩、不动效**），供文档与调试 |

命令式实例（`Modal.confirm(...)` / `useModal()` 的返回值）：

| 成员 | 说明 |
|---|---|
| `destroy()` | **关闭**（走动效 + `afterClose` 后卸载），不是立即卸载 |
| `update(config)` | 更新配置（对象浅合并，或传函数） |
| `then(resolve, reject)` | 仅 Hook 实例支持：`await api.confirm(config)` 在确认时得到 `true`，取消、销毁或 holder/owner 卸载时得到 `false` |

命令式 `onOk(close)` / `onCancel(close)` 是服务：返回 Promise 时进入 loading，成功后关闭，
拒绝则保持打开。程序内容 `footer(originNode, { OkBtn, CancelBtn })`、`modalRender(node)`
以及 `afterClose` / `afterOpenChange` 仍是 config 函数。关闭中或已关闭的实例忽略更新，
完成后从 `destroyAll` 注册中移除。Hook holder 挂载前的命令会保留，提前销毁则不再挂载。

`ModalFuncProps` 比 `ModalProps` 多 `content` / `icon` / `type` / `okCancel` /
`autoFocusButton` / `focusable.autoFocusButton`，`width` 只收 `string | number`。

### 语义化槽位（9 个）

```
root / container / wrapper / mask / header / title / body / footer / close
```

⚠️ 在 `ConfirmDialog` 里 `body` 会被摘出来，改挂到 `-confirm-content` 上。

## Theme（Component Token）

公开 6 个（可经 `theme.components.Modal` 覆盖）：`headerBg`(transparent) /
`footerBg`(transparent) / `titleLineHeight`(`lineHeightHeading5`) /
`titleFontSize`(`fontSizeHeading5`) / `titleColor`(`colorTextHeading`) /
`contentBg`(`colorBgElevated`)。

另有 **12 个 internal** token（同样落成 CSS 变量，但不在公开类型面）：
`contentPadding` / `headerPadding` / `headerBorderBottom` / `headerMarginBottom` /
`bodyPadding` / `footerPadding` / `footerBorderTop` / `footerBorderRadius` /
`footerMarginTop` / `confirmBodyPadding` / `confirmIconMarginInlineEnd` /
`confirmBtnsMarginTop` —— 全部随 `wireframe` 主题切换两套值。

## 焦点（a11y 硬要求）

1. **焦点陷阱**：`focusable.trap`（默认跟 `mask` 走）+ `visible` + 容器 `position: fixed`
   三个门都真才启用；
2. **焦点归还**：关闭后焦点回到打开前的元素（`focusable.focusTriggerAfterClose`，默认 `true`）；
   ⚠️ 上游把这条额外门控在 `mask` 上 —— **无遮罩的对话框不归还焦点**（跟随上游）；
3. **`autoFocusButton`**：确认框默认聚焦确定按钮。
   `focusable.autoFocusButton: null` 显式关闭按钮自动聚焦；旧顶层字段的 `null` 同样有效。

## 与 antd 的已知差异

见 `COMPATIBILITY.md` 的差异登记表。要点：无 `ContextIsolator`（form / space 隔离，
）；无 cssinjs 的 hash / `-css-var` 类；命令式路径用游离 `div` 承载 Vue 应用
（React 用 `DocumentFragment`）；不实现 `holderRender`。

## 迁移

普通组件 `afterClose` / `afterOpenChange` props 改为 `@after-close` /
`@after-open-change`（`h()` 中使用 `onAfterClose` / `onAfterOpenChange`）；`@ok` 和
`@cancel` 为类型化 Vue 事件。普通 `modalRender` 改为 `#modalRender` 并渲染作用域中的
`ModalPanel` 组件。普通 footer 内容使用 `#footer` 及其中的按钮组件。
命令式 config 的业务服务与程序内容职责保留。

普通旧 `focusTrap` 声明未被 runtime 消费，已移除，使用 `focusable.trap`。命令式
config 的旧 `open` 继承字段也没有统一有效消费，现已移除：调用即打开，`destroy()`
关闭，`update()` 仅更新仍存活会话的内容与有效配置，不负责重开。

命令式 `update({ confirmLoading: true })` 可显式显示确定按钮加载态并阻止点击；
更新为 `false` 后恢复业务 Promise 自身的 loading，尚未结算的 Promise 仍显示加载态。


## async (async)

点击确定后异步关闭对话框，例如提交表单。

### async.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/async.tsx：onOk 返回 Promise ⇒ 按钮自动进入 loading
import { Button, Modal } from '@apollo-design/ui';

const handleOk = () =>
  new Promise<void>((resolve) => {
    setTimeout(resolve, 1000);
  });

const showAsync = () => {
  Modal.confirm({
    title: 'Do you want to delete these items?',
    content: 'When clicked the OK button, this dialog will be closed after 1 second',
    onOk: () => handleOk(),
  });
};
</script>

<template>
  <Button @click="showAsync">Open modal with async logic</Button>
</template>
```

## basic (basic)

第一个对话框。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic.tsx
import { Button, Modal } from '@apollo-design/ui';
import { ref } from 'vue';

const isModalOpen = ref(false);

const showModal = () => {
  isModalOpen.value = true;
};
const handleOk = () => {
  isModalOpen.value = false;
};
const handleCancel = () => {
  isModalOpen.value = false;
};
</script>

<template>
  <Button type="primary" @click="showModal">Open Modal</Button>
  <Modal
    title="Basic Modal"
    :closable="{ 'aria-label': 'Custom Close Button' }"
    :open="isModalOpen"
    @ok="handleOk"
    @cancel="handleCancel"
  >
    <p>Some contents...</p>
    <p>Some contents...</p>
    <p>Some contents...</p>
  </Modal>
</template>
```

## button-props (button-props)

传递属性给按钮，例如：修改按钮的基础属性。

### button-props.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/button-props.tsx
import { Button, Modal } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
</script>

<template>
  <Button type="primary" style="max-width: 100%; height: auto; min-height: 32px; white-space: normal" @click="open = true">Open Modal with customized button props</Button>
  <Modal
    title="Basic Modal"
    :open="open"
    :ok-button-props="{ disabled: true }"
    :cancel-button-props="{ disabled: true }"
    @ok="open = false"
    @cancel="open = false"
  >
    <p>Some contents...</p>
    <p>Some contents...</p>
    <p>Some contents...</p>
  </Modal>
</template>
```

## component-token (component-token)

修改组件单独 token，标题行高、字体大小、字体颜色。

### component-token.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/component-token.tsx（含 wireframe 变体）
import { ConfigProvider, Modal } from '@apollo-design/ui';

/** Test usage. Do not use in your production. */
const InternalPanel = Modal._InternalPanelDoNotUseOrYouWillBeFired;

const modalTheme = {
  components: {
    Modal: {
      footerBg:
        'color-mix(in srgb, var(--apollo-color-success) 10%, var(--apollo-color-bg-elevated))',
      contentBg: 'color-mix(in srgb, var(--apollo-color-info) 8%, var(--apollo-color-bg-elevated))',
      headerBg:
        'color-mix(in srgb, var(--apollo-color-primary) 12%, var(--apollo-color-bg-elevated))',
      titleLineHeight: 3,
      titleFontSize: 12,
      titleColor: 'var(--apollo-color-primary-text)',
    },
  },
};
</script>

<template>
  <ConfigProvider :theme="modalTheme">
    <div style="display: flex; flex-direction: column; row-gap: 16px">
      <InternalPanel title="Hello World!" :style="{ width: '100%' }">
        Hello World?!
      </InternalPanel>
      <ConfigProvider :theme="{ token: { wireframe: true } }">
        <InternalPanel title="Hello World!" :style="{ width: '100%' }">
          Hello World?!
        </InternalPanel>
      </ConfigProvider>
      <InternalPanel type="success" :style="{ width: '200px', maxWidth: '100%' }">A good news!</InternalPanel>
      <InternalPanel title="Confirm This?" type="confirm" :style="{ width: '300px', maxWidth: '100%' }">
        Some descriptions.
      </InternalPanel>
    </div>
  </ConfigProvider>
</template>
```

## confirm (confirm)

使用 `confirm()` 可以快捷地弹出确认框。

### confirm.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/confirm.tsx（四种 confirm 形态）
import { ExclamationCircleFilled } from '@apollo-design/icons';
import { Button, Modal, Space } from '@apollo-design/ui';
import { h } from 'vue';

const showConfirm = () => {
  Modal.confirm({
    title: 'Do you want to delete these items?',
    icon: h(ExclamationCircleFilled),
    content: 'Some descriptions',
    onOk() {
      console.log('OK');
    },
    onCancel() {
      console.log('Cancel');
    },
  });
};

const showPromiseConfirm = () => {
  Modal.confirm({
    title: 'Do you want to delete these items?',
    icon: h(ExclamationCircleFilled),
    content: 'When clicked the OK button, this dialog will be closed after 1 second',
    onOk() {
      return new Promise((resolve, reject) => {
        setTimeout(Math.random() > 0.5 ? resolve : reject, 1000);
      }).catch(() => console.log('Oops errors!'));
    },
    onCancel() {},
  });
};

const showDeleteConfirm = () => {
  Modal.confirm({
    title: 'Are you sure delete this task?',
    icon: h(ExclamationCircleFilled),
    content: 'Some descriptions',
    okText: 'Yes',
    okType: 'danger',
    cancelText: 'No',
    onOk() {
      console.log('OK');
    },
    onCancel() {
      console.log('Cancel');
    },
  });
};

const showPropsConfirm = () => {
  Modal.confirm({
    title: 'Are you sure delete this task?',
    icon: h(ExclamationCircleFilled),
    content: 'Some descriptions',
    okText: 'Yes',
    okType: 'danger',
    okButtonProps: { disabled: true },
    cancelText: 'No',
    onOk() {
      console.log('OK');
    },
    onCancel() {
      console.log('Cancel');
    },
  });
};
</script>

<template>
  <Space wrap>
    <Button @click="showConfirm">Confirm</Button>
    <Button @click="showPromiseConfirm">With promise</Button>
    <Button type="dashed" @click="showDeleteConfirm">Delete</Button>
    <Button type="dashed" @click="showPropsConfirm">With extra props</Button>
  </Space>
</template>
```

## confirm-router (confirm-router)

在确认框里做「跳转」这类有副作用的操作（上游用路由，本 demo 用一段状态代替）。

### confirm-router.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/confirm-router.tsx（上游用路由跳转；本 demo 用一段文案代替跳转目标）
import { ExclamationCircleOutlined } from '@apollo-design/icons';
import { Button, Modal } from '@apollo-design/ui';
import { h, ref } from 'vue';

const current = ref('home');

const navigate = () => {
  Modal.confirm({
    title: 'Do you want to leave this page?',
    icon: h(ExclamationCircleOutlined),
    content: 'All unsaved changes will be lost.',
    onOk() {
      current.value = 'about';
    },
    onCancel() {
      current.value = 'home';
    },
  });
};
</script>

<template>
  <p>Current page: {{ current }}</p>
  <Button @click="navigate">Leave this page</Button>
</template>
```

## custom-mouse-position (custom-mouse-position)

通过 `mousePosition` 指定动画展开的原点。

### custom-mouse-position.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/custom-mouse-position.tsx
import { Button, Modal } from '@apollo-design/ui';
import { ref } from 'vue';

const isModalOpen = ref(false);
</script>

<template>
  <Button type="primary" @click="isModalOpen = true">Open Modal</Button>
  <Modal
    title="Basic Modal"
    :open="isModalOpen"
    :mouse-position="{ x: 300, y: 300 }"
    @ok="isModalOpen = false"
    @cancel="isModalOpen = false"
  >
    <p>Some contents...</p>
    <p>Some contents...</p>
    <p>Some contents...</p>
  </Modal>
</template>
```

## dark (dark)

点击按钮打开暗色对话框；内部的开关、滑块和时间轴都继承 `darkAlgorithm`。切换开关可禁用滑块。

### dark.vue

```vue
<script setup lang="ts">
import { darkAlgorithm } from '@apollo-design/theme';
import { Button, ConfigProvider, Modal, Slider, Space, Switch, Timeline } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const disabled = ref(false);
const value = ref(30);
const items = [
  { content: 'Create a service' },
  { content: 'Configure the deployment' },
  { content: 'Complete the operation' },
];
</script>

<template>
  <ConfigProvider :theme="{ algorithm: darkAlgorithm }">
    <Button type="primary" @click="open = true">Open dark modal</Button>
    <Modal title="Dark Modal" :open="open" @ok="open = false" @cancel="open = false">
      <Space wrap style="margin-bottom: 40px">
        <span>Disable slider</span>
        <Switch v-model:checked="disabled" aria-label="Disable dark modal slider" />
      </Space>
      <Slider v-model:value="value" :disabled="disabled" aria-label-for-handle="Dark modal value" />
      <Timeline :items="items" style="margin-top: 24px" />
    </Modal>
  </ConfigProvider>
</template>
```

## footer (footer)

更复杂的例子，自定义了页脚的按钮，点击提交后进入 loading 状态，完成后关闭。

### footer.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/footer.tsx：自定义 footer + 异步关闭
import { Button, Modal } from '@apollo-design/ui';
import { ref } from 'vue';

const loading = ref(false);
const open = ref(false);

const handleOk = () => {
  loading.value = true;
  setTimeout(() => {
    loading.value = false;
    open.value = false;
  }, 3000);
};

const handleCancel = () => {
  open.value = false;
};
</script>

<template>
  <Button type="primary" style="max-width: 100%; height: auto; min-height: 32px; white-space: normal" @click="open = true">Open Modal with customized footer</Button>
  <Modal
    :open="open"
    :confirm-loading="loading"
    @ok="handleOk"
    @cancel="handleCancel"
  >
    <template #footer>
      <Button key="back" @click="handleCancel">Return</Button>
      <Button key="submit" type="primary" :loading="loading" @click="handleOk">
        Submit
      </Button>
      <Button key="link" href="https://google.com" type="primary" target="_blank">
        Search on Google
      </Button>
    </template>
  </Modal>
</template>
```

## footer-render (footer-render)

自定义页脚渲染函数，可以复用默认页脚组件（`OkBtn` / `CancelBtn`）。

### footer-render.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/footer-render.tsx：自定义 footer（Vue 用 #footer slot）
import { Button, Modal, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
</script>

<template>
  <Button type="primary" style="max-width: 100%; height: auto; min-height: 32px; white-space: normal" @click="open = true">Open Modal with customized footer</Button>
  <Modal
    title="Custom Footer Render"
    :open="open"
    @ok="open = false"
    @cancel="open = false"
  >
    <p>Some contents...</p>
    <template #footer="{ OkBtn, CancelBtn }">
      <Space wrap>
        <component :is="CancelBtn" />
        <Button danger type="primary" @click="open = false">Custom</Button>
        <component :is="OkBtn" />
      </Space>
    </template>
  </Modal>
</template>
```

## hooks (hooks)

通过 `useModal` 钩子调用 modal 的方法，返回的实例可以更新与销毁。

### hooks.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/hooks.tsx：useModal 拿到的实例可以按需更新与销毁

import { ExclamationCircleOutlined } from '@apollo-design/icons';
import { Button, Modal, Space } from '@apollo-design/ui';
import { h } from 'vue';

const [modal, contextHolder] = Modal.useModal();

const countDown = () => {
  let secondsToGo = 5;
  const instance = modal.success({
    title: 'This is a notification message',
    content: `This modal will be destroyed after ${secondsToGo} second.`,
  });
  const timer = setInterval(() => {
    secondsToGo -= 1;
    instance.update({
      content: `This modal will be destroyed after ${secondsToGo} second.`,
    });
  }, 1000);
  setTimeout(() => {
    clearInterval(timer);
    instance.destroy();
  }, secondsToGo * 1000);
};

const confirm = () => {
  modal.confirm({
    title: 'Confirm',
    icon: h(ExclamationCircleOutlined),
    content: 'Bla bla ...',
    okText: '确认',
    cancelText: '取消',
  });
};
</script>

<template>
  <Space wrap>
    <Button @click="countDown">Open modal to close in 5s</Button>
    <Button @click="confirm">Confirm</Button>
  </Space>
  <component :is="contextHolder" />
</template>
```

## loading (loading)

设置 `loading` 属性后，内容区域会展示骨架屏。

### loading.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/loading.tsx
import { Button, Modal } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);

const showLoading = () => {
  open.value = true;
  setTimeout(() => {
    open.value = false;
  }, 3000);
};
</script>

<template>
  <Button type="primary" @click="showLoading">Open Modal</Button>
  <Modal title="Loading Modal" :open="open" loading>
    <p>Some contents...</p>
    <template #footer></template>
  </Modal>
</template>
```

## locale (locale)

通过 `okText` / `cancelText` 定制按钮文案。

### locale.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/locale.tsx
import { ExclamationCircleOutlined } from '@apollo-design/icons';
import { Button, Modal, Space } from '@apollo-design/ui';
import { h, ref } from 'vue';

const [modal, contextHolder] = Modal.useModal();
const open = ref(false);

const confirm = () => {
  modal.confirm({
    title: 'Confirm',
    icon: h(ExclamationCircleOutlined),
    content: 'Bla bla ...',
    okText: '确认',
    cancelText: '取消',
  });
};
</script>

<template>
  <Space wrap>
    <Button type="primary" @click="open = true">Modal</Button>
    <Button @click="confirm">Confirm</Button>
  </Space>
  <Modal
    title="Modal"
    :open="open"
    ok-text="确认"
    cancel-text="取消"
    @ok="open = false"
    @cancel="open = false"
  >
    <p>Bla bla ...</p>
    <p>Bla bla ...</p>
    <p>Bla bla ...</p>
  </Modal>
  <component :is="contextHolder" />
</template>
```

## manual (manual)

手动更新和移除，配合定时器演示。

### manual.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/manual.tsx
import { Button, Modal } from '@apollo-design/ui';

const [modal, contextHolder] = Modal.useModal();

const countDown = () => {
  let secondsToGo = 5;

  const instance = modal.success({
    title: 'This is a notification message',
    content: `This modal will be destroyed after ${secondsToGo} second.`,
  });

  const timer = setInterval(() => {
    secondsToGo -= 1;
    instance.update({
      content: `This modal will be destroyed after ${secondsToGo} second.`,
    });
  }, 1000);

  setTimeout(() => {
    clearInterval(timer);
    instance.destroy();
  }, secondsToGo * 1000);
};
</script>

<template>
  <Button @click="countDown">Open modal to close in 5s</Button>
  <component :is="contextHolder" />
</template>
```

## mask (mask)

遮罩的三种形态：模糊 / 半透明 / 不渲染。

### mask.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/mask.tsx
import { Button, Modal, Space } from '@apollo-design/ui';

const modalConfig = {
  title: 'Title',
  content: 'Some contents...',
};

const [modal, contextHolder] = Modal.useModal();
</script>

<template>
  <Space wrap>
    <Button @click="modal.confirm({ ...modalConfig, mask: { blur: true } })">blur</Button>
    <Button @click="modal.confirm(modalConfig)">Dimmed mask</Button>
    <Button @click="modal.confirm({ ...modalConfig, mask: false })">No mask</Button>
  </Space>
  <component :is="contextHolder" />
</template>
```

## modal-render (modal-render)

自定义对话框的渲染节点（`#modalRender` 作用域插槽），并用语义槽定制标题栏。

### modal-render.vue

```vue
<script setup lang="ts">
// The scoped slot supplies a stable component for the current panel.
import { Button, Modal } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
</script>

<template>
  <Button @click="open = true">Open Customized Modal</Button>
  <Modal
    title="Customized Modal"
    :open="open"
    :class-names="{ title: 'modal-draggable-title' }"
    :styles="{ title: { cursor: 'move' } }"
    @ok="open = false"
    @cancel="open = false"
  >
    <template #modalRender="{ ModalPanel }"><div class="draggable-shell"><component :is="ModalPanel" /></div></template>
    <p>Just don't learn physics at school and your life will be full of magic and miracles.</p>
    <p>Day before yesterday I saw a rabbit, and yesterday a deer, and today, you.</p>
  </Modal>
</template>
```

## nested (nested)

嵌套弹窗，三层叠加。

### nested.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/nested.tsx（去掉 message/notification/Select，只留三层嵌套 Modal）
import { Button, Modal, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);

const onShowStatic = () => {
  Modal.confirm({ title: 'Are you OK?', content: 'I am OK' });
};
</script>

<template>
  <Space wrap>
    <Button @click="open = !open">{{ open ? 'Close' : 'Open' }}</Button>
    <Button @click="onShowStatic">Static</Button>
  </Space>
  <Modal
    title="Basic Modal"
    :open="open"
    destroy-on-hidden
    :mask="{ closable: false }"
    :closable="false"
    :styles="{ container: { marginBlockStart: '100px' } }"
    @cancel="open = false"
  >
    <p>Some contents...</p>
    <template #footer></template>
    <Modal
      title="Nested Modal"
      :open="open"
      destroy-on-hidden
      :mask="false"
      :closable="false"
      :styles="{
        container: { marginBlockStart: '250px' },
        body: { display: 'flex', justifyContent: 'center' },
      }"
      @cancel="open = false"
    >
      <p>Nested contents...</p>
      <template #footer></template>
      <Modal
        title="Nested Modal"
        :open="open"
        destroy-on-hidden
        :mask="false"
        :closable="false"
        :styles="{
          container: { marginBlockStart: '400px' },
          body: { display: 'flex', justifyContent: 'flex-end' },
        }"
        @cancel="open = false"
      >
        <Button @click="onShowStatic">Static Confirm</Button>
        <template #footer></template>
      </Modal>
    </Modal>
  </Modal>
</template>
```

## position (position)

通过 `style.top` 与 `centered` 控制对话框的垂直位置。

### position.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/position.tsx
import { Button, Modal } from '@apollo-design/ui';
import { ref } from 'vue';

const modal1Open = ref(false);
const modal2Open = ref(false);
</script>

<template>
  <Button type="primary" style="max-width: 100%; height: auto; min-height: 32px; white-space: normal" @click="modal1Open = true">Display a modal dialog at 20px to Top</Button>
  <Modal
    title="20px to Top"
    :style="{ top: '20px' }"
    :open="modal1Open"
    @ok="modal1Open = false"
    @cancel="modal1Open = false"
  >
    <p>some contents...</p>
    <p>some contents...</p>
    <p>some contents...</p>
  </Modal>
  <br />
  <br />
  <Button type="primary" style="max-width: 100%; height: auto; min-height: 32px; white-space: normal" @click="modal2Open = true">Vertically centered modal dialog</Button>
  <Modal
    title="Vertically centered modal dialog"
    centered
    :open="modal2Open"
    @ok="modal2Open = false"
    @cancel="modal2Open = false"
  >
    <p>some contents...</p>
    <p>some contents...</p>
    <p>some contents...</p>
  </Modal>
</template>
```

## render-panel (render-panel)

调试用面板（`_InternalPanelDoNotUseOrYouWillBeFired`），不 portal、不遮罩、不动效。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/render-panel.tsx
import { Button, Modal, Space } from '@apollo-design/ui';

/** Test usage. Do not use in your production. */
const InternalPanel = Modal._InternalPanelDoNotUseOrYouWillBeFired;
</script>

<template>
  <div style="display: flex; flex-direction: column; row-gap: 16px">
    <InternalPanel title="Hello World!" :style="{ width: '100%', height: '200px' }">
      Hello World?!
    </InternalPanel>
    <InternalPanel type="success" :style="{ width: '200px', maxWidth: '100%', height: '150px' }">
      A good news!
    </InternalPanel>
    <InternalPanel title="Confirm This?" type="confirm" :style="{ width: '300px', maxWidth: '100%', height: '200px' }">
      Some descriptions.
    </InternalPanel>
    <InternalPanel
      title="Custom Footer Render"
      :style="{ width: '380px', maxWidth: '100%', height: '200px' }"
    >
      <p>Custom footer content.</p>
      <template #footer>
        <Space wrap>
          <Button>Cancel</Button>
          <Button danger type="primary">Custom</Button>
          <Button type="primary">OK</Button>
        </Space>
      </template>
    </InternalPanel>
  </div>
</template>
```

## static-info (static-info)

各种类型的消息对话框，通过静态方法调用。

### static-info.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/static-info.tsx
import { Button, Modal, Space } from '@apollo-design/ui';

const info = () => {
  Modal.info({
    title: 'This is a notification message',
    content: 'some messages...some messages...',
    onOk() {},
  });
};

const success = () => {
  Modal.success({ content: 'some messages...some messages...' });
};

const error = () => {
  Modal.error({
    title: 'This is an error message',
    content: 'some messages...some messages...',
  });
};

const warning = () => {
  Modal.warning({
    title: 'This is a warning message',
    content: 'some messages...some messages...',
  });
};
</script>

<template>
  <Space wrap>
    <Button @click="info">Info</Button>
    <Button @click="success">Success</Button>
    <Button @click="error">Error</Button>
    <Button @click="warning">Warning</Button>
  </Space>
</template>
```

## style-class (style-class)

通过 `classNames` / `styles` 语义槽定制对话框的各个区域（支持函数形态）。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx（上游用 antd-style；本 demo 用普通类名与内联样式表达同一意图）
import { Button, Modal } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const footerEnabled = ref(true);

const classNames = { container: 'modal-custom-container' };

/** 函数形态：按 footer 开关决定样式 */
const stylesFn = () => {
  if (footerEnabled.value) {
    return {
      container: { borderRadius: '14px', border: '1px solid #ccc', padding: 0, overflow: 'hidden' },
      header: { padding: '16px' },
      body: { padding: '16px' },
      footer: { padding: '16px 10px', backgroundColor: '#fafafa' },
    };
  }
  return {};
};
</script>

<template>
  <Button type="primary" @click="open = true">Open Modal</Button>
  <Modal
    title="Custom Styles"
    :open="open"
    :class-names="classNames"
    :styles="stylesFn"
    @ok="open = false"
    @cancel="open = false"
  >
    <div style="line-height: 28px">🌈 Enterprise-class UI designed for web applications.</div>
    <div style="line-height: 28px">📦 A set of high-quality components out of the box.</div>
    <div style="line-height: 28px">🎨 Powerful theme customization in every detail.</div>
    <template #footer v-if="!footerEnabled"></template>
  </Modal>
</template>

<style>
.modal-custom-container {
  border-radius: 10px;
  padding: 10px;
}
</style>
```

## width (width)

设置 `width` 自定义对话框宽度。

### width.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/width.tsx
import { Button, Modal } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
</script>

<template>
  <Button type="primary" @click="open = true">Open Modal</Button>
  <Modal
    title="Custom Width"
    :width="1000"
    :open="open"
    @ok="open = false"
    @cancel="open = false"
  >
    <p>Some contents...</p>
    <p>Some contents...</p>
    <p>Some contents...</p>
  </Modal>
</template>
```

## wireframe (wireframe)

线框化风格（`wireframe` 主题）。

### wireframe.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/wireframe.tsx
import { Button, ConfigProvider, Modal } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
</script>

<template>
  <ConfigProvider :theme="{ token: { wireframe: true } }">
    <Button type="primary" @click="open = true">Open Modal</Button>
    <Modal title="Wireframe Modal" :open="open" @ok="open = false" @cancel="open = false">
      <p>Some contents...</p>
      <p>Some contents...</p>
      <p>Some contents...</p>
    </Modal>
  </ConfigProvider>
</template>
```

---

# Notification

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/notification


全局展示通知提醒信息，可指定六个方位。命令式 API（`notification.success({ title })`），浮层走 portal。

## 何时使用

- 需要比 `message` 更重、可带**标题 + 描述 + 操作按钮**的通知。
- 需要按方位出现（右上角 / 右下角 / 顶部居中…）。
- 需要「自动关闭倒计时」的进度条（`showProgress`）。
- ⚠️ 优先用 `notification.useNotification()` 的 `contextHolder`：静态方法**无法消费 context**。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/notification/demo)（14 个，覆盖 antd 的主要用户场景）：basic / component-token / custom-icon /
duration / hooks / placement / progress-color / render-panel / show-with-progress /
stack / style-class / update / with-btn / with-icon。

## API

### 静态方法

| 方法 | 说明 | 签名 |
|---|---|---|
| `notification.success` / `info` / `warning` / `error` | 打开一条对应类型的通知 | `(config: ArgsProps) => void` |
| `notification.open` | 完整配置打开 | `(config: ArgsProps) => void` |
| `notification.destroy` | 关闭（传 key 关一条，不传清空） | `(key?: string \| number) => void` |
| `notification.config` | 全局默认配置（**合并**语义） | `(config: GlobalConfigProps) => void` |
| `notification.useNotification` | hooks 形态 | `(config?) => [NotificationInstance, () => VNode]` |
| `notification._InternalPanelDoNotUseOrYouWillBeFired` | 私有：单条静态面板 | 组件 |
| `notification._InternalListDoNotUseOrYouWillBeFired` | 私有：静态列表 | 组件 |

> ⚠️ **`open()` 返回 `void`** —— 与 `message` 不同，notification 没有 thenable/可调用句柄；
> 也没有 `loading` 类型（`IconType` 只有 4 个值）。

### `ArgsProps`

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 标题 | `VNodeChild` | — |
| description | 描述。与 title 同时存在时包 `-notice-section` | `VNodeChild` | — |
| actions | 操作区 | `VNodeChild` | — |
| type | `'success' \| 'info' \| 'error' \| 'warning'` | — | — |
| placement | 六个方位之一；**单条优先于全局** | `NotificationPlacement` | `'topRight'` |
| duration | 秒；`0` / `false` ⇒ 不自动关闭 | `number \| false` | `4.5` |
| showProgress | 显示自动关闭倒计时进度条 | `boolean` | — |
| pauseOnHover | 悬停暂停计时 | `boolean` | `true` |
| closable | 关闭按钮。`false` / `null` ⇒ **不渲染按钮** | `boolean \| null \| { closeIcon?, disabled?, onClose? }` | `true` |
| closeIcon | 自定义关闭图标；`null` ⇒ 不渲染按钮（上游语义） | `VNodeChild` | — |
| icon | 自定义图标（**给了就不叠 `-notice-icon-{type}` 类**） | `VNodeChild` | 类型图标 |
| role | notice 根的 ARIA 角色 | `'alert' \| 'status'` | `'alert'` |
| key | 唯一标识；同 key 再 open ⇒ 复用同一条 | `string \| number` | 自动生成 |
| onClose | 关闭按钮或超时调用最新订阅；destroy、淘汰、卸载不调用 | `() => void` | — |
| onClick | 点击订阅 | `(event: MouseEvent) => void` | — |
| className / style / classNames / styles / props | 单条根 class/style、单条语义对象及原生根属性 | — | — |
| message / btn | ⚠️ 已废弃：用 `title` / `actions` | — | — |

### Slots（C8-R2，仅 `_InternalPanelDoNotUseOrYouWillBeFired` 静态面板）

| Slot | 说明 | 参数 |
|---|---|---|
| title | 富标题（文本 `title` prop 等价，slot 优先） | — |
| message | ⚠️ 废弃别名，同 `title` | — |
| description | 富描述（文本 `description` prop 等价，slot 优先） | — |
| icon | 自定义图标（空 slot 等价隐藏） | — |
| actions | 操作区（空 slot 等价隐藏） | — |
| btn | ⚠️ 废弃别名，同 `actions` | — |
| closeIcon | 自定义关闭图标（空 slot 等价隐藏） | — |

> `notification.open({ title, description, icon, actions, closeIcon })` 的命令式入参保持 `VNodeChild`（程序化上下文，无模板）。

### `GlobalConfigProps`（`config()`）

`top` / `bottom` / `duration` / `showProgress` / `pauseOnHover` / `prefixCls` /
`getContainer` / `placement` / `closeIcon` / `closable` / `rtl` / `maxCount` / `props`。

### `NotificationConfig`（`useNotification()`）

同上，另有 `stack`（`boolean | { threshold }`，**默认 `{ offset: 8 }` ⇒ 默认就堆叠**）
与 `classNames` / `styles`。

### 语义化槽位（11 个）

```
list / listContent                                    // 列表级
wrapper / root / title / description / actions / icon / section / close / progress   // 单条级
```

> ⚠️ `classNames` / `styles` 使用对象。`list` / `listContent` 只属于 NotificationConfig 和 PureList；单条 Args 与 PurePanel 只接受单条字段。

### 类型导出

`NotificationArgsProps`、`NotificationGlobalConfigProps`、`NotificationConfig`、
`NotificationInstance`、`NotificationPlacement`、`NotificationIconType`、`NotificationSemanticType`。

## Theme（Component Token）

7 个键（CSS 变量 `--apollo-notification-*`），其中 3 个有默认值：

| token | 值 |
|---|---|
| `zIndexPopup` | `zIndexPopupBase + CONTAINER_MAX_OFFSET(1000) + 50` = **2050**（⚠️ message 是 `+10`） |
| `width` | `384` |
| `progressBg` | `linear-gradient(90deg, colorPrimaryBorderHover, colorPrimary)` |
| `colorSuccessBg` / `colorErrorBg` / `colorInfoBg` / `colorWarningBg` | 默认 `undefined`（产物是带 fallback 的 `var()`） |

## 设计说明

### 与 message 共用通知内核

两者都建立在 `notification/engine/`（rc-notification 的 Vue 自建）之上；差异只在配置翻译
与 notice 内部的语义（notification 有标题 + 描述 + 操作区 + 关闭按钮，message 只有一行文本）。

### 默认就堆叠

`DEFAULT_STACK_CONFIG = { offset: 8 }` ⇒ 列表根恒带 `-stack` 类，超过阈值（默认 3）自动折叠。
`message` 的默认是 `false`（不堆叠）—— 这是两者最容易搞混的一处。

### 样式引入

```ts
import '@apollo-design/theme/dist/tokens.css';      // 主题变量，必须先引
import '@apollo-design/ui/notification/style.css';  // 按需
// 或
import '@apollo-design/ui/style.css';               // 汇总
```

## FAQ

**为什么关闭按钮有时没有图标？**

`closable: false` 或 `closeIcon: null` 会**整个移除按钮**（上游语义）；
要「有按钮但不渲染图标」请用 `closable: { closeIcon: null }`。

**`duration: 0` 和 `duration: false` 有区别吗？**

没有 —— 都会被归一化成 `false`（不自动关闭）。

**同 key 再 open 会怎样？**

复用同一条通知并更新内容（`update` demo），不会新增一条。


Hook holder 内已打开通知保留 keyed 正文与用户样式；类型、图标和关闭按钮类跟随当前前缀，默认关闭可访问名跟随当前语言，显式 closable aria-label 优先。closable.disabled 禁用原生关闭按钮。

PurePanel 的 `closable` 只描述图标、disabled 和可访问名等展示配置，关闭使用类型化 `@close`。原来未被消费的嵌套 `closable.onClose` 已移除；命令式 Args、hook/global 的订阅职责保持。


### Vue 契约与迁移

在 setup 中调用 `useNotification`，将零参 holder factory 作为组件渲染，或调用它取得 VNode。挂载前命令排队等候该 holder 就绪，owner 卸载后不再执行。同 key 更新保留内容身份并重新开始计时，数值 key 与字符串 key 保持独立。

PurePanel 将原生 `class`、`style`、attrs 和类型化 `@click` / `@close` 作用到实际宿主。旧 `className` 改用 `class`；富内容使用具名槽并保留 `0` 与显式空内容。PureList 的语义样式映射改用 `styles`，原生 `style` 设置其宿主样式。`getContainer` 可返回 HTMLElement 或 ShadowRoot。

当前 holder 配置和 Provider 对象可替换或撤除，七个 Token 与默认语言跟随当前上下文。列表数值 z-index 覆盖（含 `0` 和数值字符串）同时提供后代 popup 上下文；CSS 表达式保持原样，数值上下文使用当前 Token。静态方法读取 ConfigProvider 全局服务，不注入调用组件的上下文。


## basic (basic)

静态方法无法消费 Context，不能动态响应 ConfigProvider 提供的各项配置。请优先使用 hooks 版本或者 App 组件提供的 `notification` 实例。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic.tsx —— 静态方法（无法消费 context，推荐 hooks 形态）
import { Button, notification } from '@apollo-design/ui';
import { onBeforeUnmount, useId } from 'vue';

const key = useId();
onBeforeUnmount(() => notification.destroy(key));

const openNotification = () => {
  notification.open({
    key,
    title: 'Notification Title',
    description:
      'This is the content of the notification. This is the content of the notification. This is the content of the notification.',
    onClick: () => {
      console.log('Notification Clicked!');
    },
  });
};
</script>

<template>
  <Button type="primary" @click="openNotification">Open the notification box</Button>
</template>
```

## component-token (component-token)

通过 `ConfigProvider` 动态设置通知宽度、进度条与各状态背景色，切换按钮可移除或恢复局部组件 Token。

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, Flex, notification } from '@apollo-design/ui';
import { ref } from 'vue';

const InternalPanel = notification._InternalPanelDoNotUseOrYouWillBeFired;
const custom = ref(true);
const theme = {
  components: {
    Notification: {
      width: 320,
      zIndexPopup: 2200,
      progressBg: 'var(--apollo-color-success)',
      colorSuccessBg: 'var(--apollo-color-success-bg)',
      colorErrorBg: 'var(--apollo-color-error-bg)',
      colorInfoBg: 'var(--apollo-color-info-bg)',
      colorWarningBg: 'var(--apollo-color-warning-bg)',
    },
  },
};
</script>

<template>
  <Flex vertical gap="middle" align="flex-start">
    <Button @click="custom = !custom">{{ custom ? 'Use default tokens' : 'Use custom tokens' }}</Button>
    <InternalPanel title="Default notification" description="Default width and surface." type="info" />
    <ConfigProvider :theme="custom ? theme : undefined">
      <InternalPanel title="Custom notification" description="Width and state surface follow the current component tokens." type="success" />
    </ConfigProvider>
  </Flex>
</template>
```

## custom-icon (custom-icon)

自定义图标。

### custom-icon.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/custom-icon.tsx —— 自定义 icon
import { SmileOutlined } from '@apollo-design/icons';
import { Button, notification } from '@apollo-design/ui';
import { h } from 'vue';

const [api, contextHolder] = notification.useNotification();

const openNotification = () => {
  api.open({
    title: 'Notification Title',
    description:
      'This is the content of the notification. This is the content of the notification. This is the content of the notification.',
    icon: h(SmileOutlined, { style: { color: '#108ee9' } }),
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Button type="primary" @click="openNotification">Open the notification box</Button>
</template>
```

## duration (duration)

自定义通知框自动关闭的延时，默认 `4.5s`，取消自动关闭只要将该值设为 `0` 即可。

### duration.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/duration.tsx —— duration: 0 ⇒ 不自动关闭（默认 4.5s）
import { Button, notification } from '@apollo-design/ui';

const [api, contextHolder] = notification.useNotification();

const openNotification = () => {
  api.open({
    title: 'Notification Title',
    description:
      'I will never close automatically. This is a purposely very very long description that has many many characters and words.',
    duration: 0,
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Button type="primary" @click="openNotification">Open the notification box</Button>
</template>
```

## hooks (hooks)

通过 `notification.useNotification` 创建支持读取 context 的 `contextHolder`。请注意，我们推荐通过顶层注册的方式代替 `notification` 静态方法，因为静态方法无法消费上下文。

### hooks.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/hooks.tsx —— hooks 形态能消费 context（这里用 provide/inject 演示）

import type { NotificationPlacement } from '@apollo-design/ui';
import { Button, Divider, notification, Space } from '@apollo-design/ui';
import { defineComponent, h, inject, provide } from 'vue';

const nameKey = Symbol('demo-name');
provide(nameKey, 'Apollo Design');
const Greeting = defineComponent({
  setup() {
    const name = inject(nameKey, 'Default');
    return () => h('span', `Hello, ${name}!`);
  },
});

const [api, contextHolder] = notification.useNotification();

const openNotification = (placement: NotificationPlacement) => {
  api.info({
    title: `Notification ${placement}`,
    // Holder 中实际挂载的后代组件读取当前示例的 provide。
    description: h(Greeting),
    placement,
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Space wrap>
    <Button type="primary" @click="openNotification('topLeft')">topLeft</Button>
    <Button type="primary" @click="openNotification('topRight')">topRight</Button>
  </Space>
  <Divider />
  <Space wrap>
    <Button type="primary" @click="openNotification('bottomLeft')">bottomLeft</Button>
    <Button type="primary" @click="openNotification('bottomRight')">bottomRight</Button>
  </Space>
</template>
```

## placement (placement)

使用 `placement` 可以配置通知从上面、下面、左上角、右上角、左下角、右下角弹出。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/placement.tsx —— 六个方位
import {
  BorderBottomOutlined,
  BorderTopOutlined,
  RadiusBottomleftOutlined,
  RadiusBottomrightOutlined,
  RadiusUpleftOutlined,
  RadiusUprightOutlined,
} from '@apollo-design/icons';
import type { NotificationPlacement } from '@apollo-design/ui';
import { Button, Divider, notification, Space } from '@apollo-design/ui';

const [api, contextHolder] = notification.useNotification();

const openNotification = (placement: NotificationPlacement) => {
  api.info({
    title: `Notification ${placement}`,
    description:
      'This is the content of the notification. This is the content of the notification. This is the content of the notification.',
    placement,
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Space wrap>
    <Button type="primary" :icon="BorderTopOutlined" @click="openNotification('top')">top</Button>
    <Button type="primary" :icon="BorderBottomOutlined" @click="openNotification('bottom')">
      bottom
    </Button>
  </Space>
  <Divider />
  <Space wrap>
    <Button type="primary" :icon="RadiusUpleftOutlined" @click="openNotification('topLeft')">
      topLeft
    </Button>
    <Button type="primary" :icon="RadiusUprightOutlined" @click="openNotification('topRight')">
      topRight
    </Button>
  </Space>
  <Divider />
  <Space wrap>
    <Button type="primary" :icon="RadiusBottomleftOutlined" @click="openNotification('bottomLeft')">
      bottomLeft
    </Button>
    <Button
      type="primary"
      :icon="RadiusBottomrightOutlined"
      @click="openNotification('bottomRight')"
    >
      bottomRight
    </Button>
  </Space>
</template>
```

## progress-color (progress-color)

使用 `Notification.progressBg` 组件 Token 设置渐变进度条。通知 Holder 位于局部 `ConfigProvider` 内，弹层继承该主题。

### progress-color.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, notification } from '@apollo-design/ui';

const [api, contextHolder] = notification.useNotification();
const theme = {
  components: {
    Notification: {
      progressBg:
        'linear-gradient(90deg, var(--apollo-color-success-border), var(--apollo-color-success))',
    },
  },
};
const openNotification = () => {
  api.open({
    title: 'Customize progress bar color',
    description: 'The progress bar uses Notification.progressBg from the nearest ConfigProvider.',
    showProgress: true,
    duration: 20,
  });
};
</script>

<template>
  <ConfigProvider :theme="theme">
    <component :is="contextHolder" />
    <Button type="primary" @click="openNotification">Show custom progress color</Button>
  </ConfigProvider>
</template>
```

## render-panel (render-panel)

调试用组件，请勿直接使用。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/render-panel.tsx —— 调试用组件，请勿直接使用
import { notification } from '@apollo-design/ui';

const InternalPanel = notification._InternalPanelDoNotUseOrYouWillBeFired;
</script>

<template>
  <component :is="InternalPanel" title="Hello World!" type="error" />
</template>
```

## show-with-progress (show-with-progress)

显示自动关闭倒计时的进度条。

### show-with-progress.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/show-with-progress.tsx —— showProgress + pauseOnHover
import { Button, notification, Space } from '@apollo-design/ui';

const [api, contextHolder] = notification.useNotification();

const openNotification = (pauseOnHover: boolean) => {
  api.open({
    title: 'Notification Title',
    description:
      'This is the content of the notification. This is the content of the notification. This is the content of the notification.',
    showProgress: true,
    pauseOnHover,
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Space wrap>
    <Button type="primary" @click="openNotification(true)">Pause on hover</Button>
    <Button type="primary" @click="openNotification(false)">Don't pause on hover</Button>
  </Space>
</template>
```

## stack (stack)

堆叠配置。超过阈值后自动收起，可以通过 `threshold` 设置触发堆叠的数量。折叠状态下仅展示最新的通知。

### stack.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/stack.tsx —— 堆叠折叠（notification **默认就堆叠**，阈值默认 3）
import { Button, Divider, InputNumber, notification, Space, Switch } from '@apollo-design/ui';
import { ref } from 'vue';

const enabled = ref(true);
const threshold = ref(3);

// ⚠️ 本仓 useNotification 接受 getter 形态的配置 ⇒ 开关与阈值改动实时生效
const [api, contextHolder] = notification.useNotification(() => ({
  stack: enabled.value ? { threshold: threshold.value } : false,
}));

const openNotification = () => {
  const count = Math.round(Math.random() * 5) + 1;
  api.open({
    title: 'Notification Title',
    description: Array.from(
      { length: count },
      () => 'This is the content of the notification.',
    ).join('\n'),
    duration: false,
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Space wrap size="large">
    <Space wrap>
      <span>Enabled: </span>
      <!-- ⚠️ 比 antd 的 demo 多了 aria-label：axe 会为无名的 Switch / InputNumber 报
           button-name / label 违规，而本仓的 L5 要求 demo 零违规（教学内容不受影响） -->
      <Switch v-model:checked="enabled" aria-label="Enable notification stack" />
    </Space>
    <Space wrap>
      <span>Threshold: </span>
      <InputNumber
        v-model:value="threshold"
        aria-label="Stack threshold"
        :disabled="!enabled"
        :step="1"
        :min="1"
        :max="10"
      />
    </Space>
  </Space>
  <Divider />
  <Button type="primary" @click="openNotification">Open the notification box</Button>
</template>
```

## style-class (style-class)

通过 `classNames` 和 `styles` 可以自定义通知的语义化结构样式。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx —— 用 classNames / styles 自定义语义化结构样式

import type { NotificationArgsProps } from '@apollo-design/ui';
import { Button, notification, Space } from '@apollo-design/ui';

const defaultStyles: NonNullable<NotificationArgsProps['styles']> = {
  root: {
    backgroundColor: '#f6ffed',
    border: '2px solid #95de64',
    borderRadius: 16,
    boxShadow: '4px 4px 0 #d9f7be',
  },
  icon: { color: '#237804' },
  title: { color: '#237804', fontWeight: 600 },
};

const [api, contextHolder] = notification.useNotification();

const showObjectStyle = () => {
  api.open({
    title: 'This is a notification with object styles',
    description: 'The semantic slots can be styled with classNames and styles',
    styles: defaultStyles,
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Space wrap>
    <Button @click="showObjectStyle">Object style</Button>
  </Space>
</template>
```

## update (update)

可以通过唯一的 `key` 来更新内容。

### update.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/update.tsx —— 同 key 复用同一条通知（更新内容）
import { Button, notification } from '@apollo-design/ui';

const [api, contextHolder] = notification.useNotification();
const key = 'updatable';

const openNotification = () => {
  api.open({ key, title: 'Notification Title', description: 'description.' });
  setTimeout(() => {
    api.open({ key, title: 'New Title', description: 'New description.' });
  }, 1000);
};
</script>

<template>
  <component :is="contextHolder" />
  <Button type="primary" @click="openNotification">Open the notification box</Button>
</template>
```

## with-btn (with-btn)

自定义关闭按钮的文案。

### with-btn.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/with-btn.tsx —— actions 里放操作按钮 + onClose
import { Button, notification, Space } from '@apollo-design/ui';
import { h } from 'vue';

const [api, contextHolder] = notification.useNotification();

const close = () => {
  console.log(
    'Notification was closed. Either the close button was clicked or duration time elapsed.',
  );
};

const openNotification = () => {
  const key = `open${Date.now()}`;
  // ⚠️ SFC 里用 `h()` 而不是 JSX（要写 JSX 得 `lang="tsx"`）
  const btn = h(Space, null, () => [
    h(Button, { type: 'link', size: 'small', onClick: () => api.destroy() }, () => 'Destroy All'),
    h(Button, { type: 'primary', size: 'small', onClick: () => api.destroy(key) }, () => 'Confirm'),
  ]);
  api.open({
    title: 'Notification Title',
    description:
      'A function will be called after the notification is closed (automatically after the "duration" time or manually).',
    actions: btn,
    key,
    onClose: close,
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Button type="primary" @click="openNotification">Open the notification box</Button>
</template>
```

## with-icon (with-icon)

图标可以被设置。

### with-icon.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/with-icon.tsx —— 四种类型（带图标）

import type { NotificationIconType } from '@apollo-design/ui';
import { Button, Flex, notification } from '@apollo-design/ui';

const [api, contextHolder] = notification.useNotification();

const openNotificationWithIcon = (type: NotificationIconType) => {
  api[type]({
    title: 'Notification Title',
    description:
      'This is the content of the notification. This is the content of the notification. This is the content of the notification.',
  });
};
</script>

<template>
  <component :is="contextHolder" />
  <Flex gap="8px" wrap="wrap">
    <Button @click="openNotificationWithIcon('success')">Success</Button>
    <Button @click="openNotificationWithIcon('info')">Info</Button>
    <Button @click="openNotificationWithIcon('warning')">Warning</Button>
    <Button @click="openNotificationWithIcon('error')">Error</Button>
  </Flex>
</template>
```

---

# Pagination

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/pagination


# Pagination 分页

采用分页的形式分隔长列表，每次只加载一个页面。

## 何时使用

- 当加载/渲染所有数据将花费很多时间时；
- 当数据量太大、需要分屏展示时；
- 需要让用户快速在页之间跳转时。

## 引入

```ts
import { Pagination } from '@apollo-design/ui';
```

## 代码演示

























## API

### Pagination

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| current（`v-model:current`） | 当前页 | `number` | —— |
| defaultCurrent | 非受控初始页 | `number` | `1` |
| pageSize（`v-model:pageSize`） | 每页条数 | `number` | —— |
| defaultPageSize | 非受控初始每页条数 | `number` | `10` |
| total | 数据总数 | `number` | `0` |
| pageSizeOptions | 每页条数可选项（⚠️ 只收数字） | `number[]` | `[10, 20, 50, 100]` |
| totalBoundaryShowSizeChanger | 尺寸切换器的显示阈值 | `number` | `50` |
| showSizeChanger | 尺寸切换器：`true` / `false` / **Select 的 props 对象** | `boolean \| SelectProps` | `total > 50` |
| showQuickJumper | 快速跳转；`{ goButton }` 可自定义确认按钮 | `boolean \| { goButton?: VNodeChild }` | `false` |
| showPrevNextJumpers | 是否显示跳页项 | `boolean` | `true` |
| showLessItems | 每页显示更少的页码（buffer 2→1、跳页步长 5→3） | `boolean` | `false` |
| showTitle | 是否给 `li` 加 `title` | `boolean` | `true` |
| simple | 简化模式；`{ readOnly: true }` 时页码不可输入 | `boolean \| { readOnly?: boolean }` | `false` |
| hideOnSinglePage | 只有一页时隐藏 | `boolean` | `false` |
| disabled | 禁用 | `boolean` | `false` |
| size | 尺寸 | `'small' \| 'default' \| 'large'` | —— |
| responsive | `xs` 断点且未指定 `size` 时用 `small` | `boolean` | `false` |
| align | 整体对齐 | `'start' \| 'center' \| 'end'` | —— |
| locale | 覆盖语言包（与 ConfigProvider 的 `Pagination` 分片合并，**props 优先**） | `PaginationLocale` | —— |
| role | 根 `<ul>` 的 role | `string` | —— |
| classNames | 语义化类名：`root` / `item` | `PaginationSemanticClassNames` | —— |
| styles | 语义化样式：同上 2 槽 | `PaginationSemanticStyles` | —— |

### 事件

| 事件 | 说明 | 参数 |
| --- | --- | --- |
| `update:current` | 当前页变化（`v-model:current`） | `(current: number)` |
| `update:pageSize` | 每页条数变化（`v-model:pageSize`） | `(pageSize: number)` |
| `change` | 页码或每页条数变化（与 `update:*` 同时发出） | `(current: number, pageSize: number)` |
| `showSizeChange` | 仅每页条数变化时（⚠️ `current` 是**变化前**的页） | `(current: number, size: number)` |

### 插槽

| 插槽 | 说明 | 参数 |
| --- | --- | --- |
| `itemRender` | 自定义每一项（替代 `itemRender` prop） | `{ page, type, element }` |
| `total` | 自定义总数展示（替代 `showTotal` prop） | `{ total, range }` |
| `sizeChanger` | 自定义尺寸切换器（替代 `sizeChangerRender` / antd 的 `components.sizeChanger`） | `{ value, onSizeChange, onChange, disabled, className, options, 'aria-label' }` |

### 键盘

| 按键 | 行为 |
| --- | --- |
| Enter | 在页码 / 上一页 / 下一页 / 跳页项上触发 |
| Enter（快速跳转输入框） | 跳到输入页；↑ / ↓ 在简化模式下是 ∓1 |

`current` 与 `pageSize` 分别受控。`defaultCurrent` / `defaultPageSize` 只初始化非受控状态；外部赋值不发事件，移除控制后延续最后接收的值，不采纳被拒绝的更新请求。非受控当前页在总量收缩时保存钳制结果，随后总量回涨不会恢复旧页；受控当前页始终以传入值为准。尺寸切换仍按 `update:pageSize` → `showSizeChange` → `update:current` → `change` 的顺序通知，`showSizeChange` 的页码为切换前值。

简化输入在 Enter / 失焦后显示实际模型值，空输入恢复当前页。快速跳转失焦到本实例页码控件（含自定义槽中的按钮）时由该控件处理；移到其他分页实例仍正常提交。`goButton` 支持包含 `0` 的 Vue 内容，`true` 使用默认按钮，`false` / `null` / `undefined` 不显示确认内容。现代 `KeyboardEvent.key` 可用于 Enter 和方向键；槽内已取消的 Enter 不再由分页激活。禁用与零总量的占位项不参与 Tab 顺序并标记 `aria-disabled`，禁用时尺寸槽回调也不触发更新；尺寸必须为正整数且不同于当前值。

`showSizeChanger` 的 Select 配置使用原生 `class`，支持字符串、数组和对象；旧测试中的 `showSizeChanger.className` 写法改为 `showSizeChanger.class`，不保留该未声明别名。`classNames.item` / `styles.item` 继续控制分页项。没有公开 expose 方法，组件实例的 `$el` 指向当前根 `<ul>`（隐藏时为注释节点）。

> ⚠️ **尺寸切换器注入点有两个字段名**：rc 的 `sizeChangerRender` 实参叫 `onSizeChange`，
> antd 的 `components.sizeChanger` 叫 `onChange` —— 本仓**两个都给**（同一个函数），
> 照哪份文档写都能用（见 `COMPATIBILITY.md` 的 U14 上下文）。

## 设计 Token

| Token | 默认值（light） | 说明 |
| --- | --- | --- |
| `itemBg` / `itemActiveBg` / `itemLinkBg` / `itemInputBg` | `#ffffff` | 页码 / 激活 / 常规上一页下一页按钮 / 简化输入背景 |
| `itemSize` / `itemSizeSM` / `itemSizeLG` | `32px` / `24px` / `40px` | 页码尺寸（`controlHeight` 三档） |
| `itemActiveColor` / `itemActiveColorHover` | `#1677ff` / `#4096ff` | 激活态文字色 / hover |
| `itemActiveColorDisabled` | `rgba(0,0,0,0.25)` | 激活态禁用文字色 |
| `itemActiveBgDisabled` | `rgba(0,0,0,0.15)` | 激活态禁用背景 |
| `miniOptionsSizeChangerTop` | `0px` | mini 形态下切换器上边距 |

`ConfigProvider` 的 `theme.components.Pagination` 支持以上 12 个组件 Token；尺寸可用 CSS 字符串或数值（按 `px`），`miniOptionsSizeChangerTop` 可为负偏移。覆盖支持替换与移除，移除后从当前全局 Token 重新派生。根原生 `style` 优先于语义 root 样式，再优先于主题变量。自定义 `prefixCls` 对应同名前缀的组件变量，仍需调用方提供对应前缀样式。

快速跳转输入的字号、内边距、焦点等由当前全局 Token 派生，不是额外的 Pagination 组件覆盖字段；尺寸选择器本体使用 Select 的 Token。未启用源码主题时，组件保留静态 CSS 与祖先 CSS 变量的控制权。主题更新只写根 CSS 变量，样式规则保持静态。

原生 `#itemRender` / `#total` / `#sizeChanger` 是内容入口，三个渲染函数 prop 已直接移除，无兼容层或弃用期。页码槽覆盖 page/prev/next/jump-prev/jump-next；存在的空槽压住默认内容。插槽支持挂载后的条件出现、移除与响应式更新。`PaginationItemSlotProps` / `PaginationTotalSlotProps` / `PaginationSlots` 导出精确类型。根 id、title、原生事件及字符串/对象/数组 style 按 Vue 规则透传，与语义 root 样式合并。


## 基本 (basic)

最简单的用法：`v-model:current` 绑定当前页。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd `basic.tsx`。
import { Pagination } from '@apollo-design/ui';
import { ref } from 'vue';

const current = ref(1);
</script>

<template>
  <Pagination v-model:current="current" :total="50" />
</template>
```

## 总数 (total)

通过 `#total="{ total, range }"` 展示总数与当前范围。

### total.vue

```vue
<script setup lang="ts">
import { Pagination } from '@apollo-design/ui';
</script>

<template>
  <Pagination :total="85">
    <template #total="{ total }">Total {{ total }} items</template>
  </Pagination>
</template>
```

## 组合 (all)

尺寸切换器、快速跳转和原生总数槽组合。

### all.vue

```vue
<script setup lang="ts">
import { Pagination } from '@apollo-design/ui';
</script>

<template>
  <Pagination :total="85" show-size-changer show-quick-jumper>
    <template #total="{ total }">Total {{ total }} items</template>
  </Pagination>
</template>
```

## 改变页码大小 (changer)

`showSizeChanger` 切换每页条数；禁用态一并展示；`@show-size-change` 拿到旧页与新页大小。

### changer.vue

```vue
<script setup lang="ts">
// 对齐 antd `changer.tsx`。
import { Pagination } from '@apollo-design/ui';

const onShowSizeChange = (current: number, size: number): void => {
  console.log(current, size);
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Pagination
      show-size-changer
      :default-current="3"
      :total="500"
      @show-size-change="onShowSizeChange"
    />
    <Pagination
      show-size-changer
      :default-current="3"
      :total="500"
      disabled
      @show-size-change="onShowSizeChange"
    />
  </div>
</template>
```

## 受控 (controlled)

`v-model:current` 受控；`change` 事件与普通用法一致。

### controlled.vue

```vue
<script setup lang="ts">
// 对齐 antd `controlled.tsx`。
import { Pagination } from '@apollo-design/ui';
import { ref } from 'vue';

const current = ref(3);
const onChange = (page: number): void => {
  console.log(page);
  current.value = page;
};
</script>

<template>
  <Pagination v-model:current="current" :total="50" @change="onChange" />
</template>
```

## 简洁 (simple)

`simple` 简化模式：只有上一页/下一页 + `当前 / 总数`（可输入）。

### simple.vue

```vue
<script setup lang="ts">
// 对齐 antd `simple.tsx`。
import { Pagination } from '@apollo-design/ui';
</script>

<template>
  <Pagination simple :default-current="2" :total="50" />
</template>
```

## 跳转 (jump)

`showQuickJumper` 快速跳转；`{ goButton: true }` 加一个确认按钮。

### jump.vue

```vue
<script setup lang="ts">
// 对齐 antd `jump.tsx`。
import { Pagination } from '@apollo-design/ui';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Pagination show-quick-jumper :default-current="3" :total="500" />
    <Pagination show-quick-jumper :default-current="3" :total="500" />
  </div>
</template>
```

## 小尺寸 (mini)

`size="small"` 小尺寸；`responsive` 会在 `xs` 断点自动变紧凑。

### mini.vue

```vue
<script setup lang="ts">
// 对齐 antd `mini.tsx`。
import { Pagination } from '@apollo-design/ui';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Pagination size="small" :total="50" show-size-changer show-quick-jumper />
    <Pagination size="small" :total="50" show-size-changer show-quick-jumper disabled />
  </div>
</template>
```

## 更多 (more)

`showLessItems` 每页显示更少的页码（±3 而不是 ±5）。

### more.vue

```vue
<script setup lang="ts">
// 对齐 antd `more.tsx`。
import { Pagination } from '@apollo-design/ui';
</script>

<template>
  <Pagination :default-current="6" :total="500" show-less-items />
</template>
```

## 对齐 (align)

`align` 控制整体对齐（`start` / `center` / `end`）。

### align.vue

```vue
<script setup lang="ts">
// 对齐 antd `align.tsx`。
import { Pagination } from '@apollo-design/ui';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Pagination align="start" :default-current="1" :total="50" />
    <Pagination align="center" :default-current="1" :total="50" />
    <Pagination align="end" :default-current="1" :total="50" />
  </div>
</template>
```

## 自定义页码 (itemRender)

`#itemRender="{ page, type, element }"` 自定义每一项；空槽压住默认内容。

### itemRender.vue

```vue
<script setup lang="ts">
import { Pagination } from '@apollo-design/ui';
</script>

<template>
  <Pagination :total="500" :default-current="6">
    <template #itemRender="{ type, element }">
      <a v-if="type === 'prev'">Previous</a>
      <a v-else-if="type === 'next'">Next</a>
      <component :is="element" v-else />
    </template>
  </Pagination>
</template>
```

## 自定义切换器 (components)

通过原生 `#sizeChanger` 将尺寸切换器替换为 InputNumber，业务动作使用 onSizeChange。

### components.vue

```vue
<script setup lang="ts">
import { InputNumber, Pagination } from '@apollo-design/ui';
</script>

<template>
  <Pagination show-size-changer :default-current="3" :total="500">
    <template #sizeChanger="{ value, onSizeChange, disabled, className }">
      <InputNumber aria-label="Page Size" :class="className" :disabled="disabled" :min="1"
        style="width: 100px" :value="value"
        @change="next => { if (typeof next === 'number') onSizeChange(next); }" />
    </template>
  </Pagination>
</template>
```

## 组件 Token (component-token)

通过 `ConfigProvider` 的 `theme.components.Pagination` 自定义页码尺寸、背景色与激活态颜色；尺寸数值按 `px` 处理。

组件覆盖替换或移除后会重新读取当前全局 Token；根元素的原生 `style` 仍可覆盖对应 CSS 变量。

点击页码或切换每页条数可以看到状态变化。

### component-token.vue

```vue
<script setup lang="ts">
import { ConfigProvider, Pagination } from '@apollo-design/ui';
import { ref } from 'vue';

const current = ref(2);

const paginationTokens = {
  itemSize: 40,
  itemBg: '#fafafa',
  itemActiveBg: '#fff0f6',
  itemActiveColor: '#eb2f96',
};
</script>

<template>
  <ConfigProvider :theme="{ components: { Pagination: paginationTokens } }">
    <Pagination
      v-model:current="current"
      :total="120"
      :page-size-options="[10, 20, 50]"
      show-size-changer
    />
  </ConfigProvider>
</template>
```

## 语义化样式 (style-class)

通过 `classNames` 与 `styles` 自定义分页器根节点与每个页码项的样式。

页码悬浮时会轻微上移，点击可以切换当前页。

### style-class.vue

```vue
<script setup lang="ts">
// 语义化 classNames / styles：root / item 两个槽位。
import { Pagination } from '@apollo-design/ui';
import { ref } from 'vue';

const current = ref(1);

const classNames = {
  root: 'demo-pagination-style-root',
  item: 'demo-pagination-style-item',
};

const styles = {
  root: {
    padding: '12px 16px',
    borderRadius: '10px',
    backgroundColor: 'var(--apollo-color-fill-quaternary)',
  },
  item: { transition: 'transform 0.2s' },
};
</script>

<template>
  <Pagination v-model:current="current" :total="80" :class-names="classNames" :styles="styles" />
</template>

<style>
.demo-pagination-style-root {
  border: 1px solid var(--apollo-color-border-secondary);
}

.demo-pagination-style-item:hover {
  transform: translateY(-1px);
}
</style>
```

## 动态原生插槽 (native-slots)

使用单个具名对象定义页码、总数和尺寸切换器。条件插槽可在挂载后出现或移除，空内容压住默认页码；根原生 attrs、事件和字符串样式按 Vue 规则更新。

<!-- en-US -->

Render pages, totals and size controls through named slot objects. Add or remove slots after mount; empty content suppresses default pages. Native root attrs, events and string styles update through Vue.

### native-slots.vue

```vue
<script setup lang="ts">
import { Button, Pagination } from '@apollo-design/ui';
import { ref } from 'vue';

const current = ref(1);
const pageSize = ref(10);
const customItems = ref(false);
const customSize = ref(false);
const showTotal = ref(true);
const empty = ref(false);
const disabled = ref(false);
const label = ref('Page');
const changes = ref(0);
const sizes = ref(0);
const rootClicks = ref(0);
const nativeEvent = ref('');
const blue = ref(false);
const onRootClick = (event: MouseEvent) => {
  rootClicks.value++;
  nativeEvent.value = event instanceof MouseEvent ? event.type : 'invalid';
};
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 12px">
    <Button @click="customItems = !customItems">Toggle page slots</Button>
    <Button @click="customSize = !customSize">Toggle size slot</Button>
    <Button @click="showTotal = !showTotal">Toggle total slot</Button>
    <Button @click="empty = !empty">Toggle empty pages</Button>
    <Button @click="disabled = !disabled">Toggle pagination disabled</Button>
    <Button @click="label = label === 'Page' ? 'Current' : 'Page'">Update page label</Button>
    <Button @click="blue = !blue">Update pagination attrs</Button>
  </div>
  <Pagination id="native-pagination" v-model:current="current" v-model:pageSize="pageSize"
    :total="85" show-size-changer :disabled="disabled"
    :style="blue ? 'color:blue' : 'color:red'" aria-label="Native pagination"
    @change="changes++" @show-size-change="sizes++" @click="onRootClick">
    <template v-if="customItems" #itemRender="{ page, type, element }">
      <span v-if="!empty" :data-page-type="type" :data-page="page">
        <b v-if="type === 'page'">{{ label }} {{ page }}</b>
        <component :is="element" v-else />
      </span>
    </template>
    <template v-if="showTotal" #total="{ total, range }">
      <output data-native-total>{{ range[0] }}-{{ range[1] }} / {{ total }}</output>
    </template>
    <template v-if="customSize" #sizeChanger="{ value, onSizeChange, disabled }">
      <Button data-native-size :disabled="disabled" @click="onSizeChange(value === 10 ? 20 : 10)">
        Size {{ value }}
      </Button>
    </template>
  </Pagination>
  <output id="pagination-state" style="display: block; overflow-wrap: anywhere; margin-top: 12px">{{ JSON.stringify({ current, pageSize, changes, sizes, rootClicks, nativeEvent }) }}</output>
</template>
```

---

# Popconfirm

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/popconfirm


# Popconfirm 气泡确认框

目标元素的操作需要用户进一步的确认时使用。与 `Popover` 相比它内置了「确认 / 取消」两个按钮。

## 引入

```ts
import { Popconfirm } from '@apollo-design/ui';
```

## 代码演示





















## API

### PopconfirmProps

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| title | 标题数据（`0` 合法）；模板内容使用 `#title` | VNodeChild | - |
| description | 描述数据；模板内容使用 `#description` | VNodeChild | - |
| disabled | 是否禁用（禁用后不通过触发器展开，也不发 `openChange`） | boolean | false |
| open | 是否展开（受控） | boolean | - |
| defaultOpen | 默认是否展开 | boolean | false |
| trigger | 触发行为 | string \| string[] | 'click' |
| placement | 浮层位置 | TooltipPlacement | 'top' |
| okText | 确认按钮文案；为空回退 locale。富内容走 `#okText` 插槽（优先） | string \| slot | OK |
| okType | 确认按钮类型 | LegacyButtonType | 'primary' |
| cancelText | 取消按钮文案；为空回退 locale。富内容走 `#cancelText` 插槽（优先） | string \| slot | Cancel |
| okButtonProps | 确认按钮属性；根类名使用 Vue 原生 `class` | PopconfirmButtonProps | - |
| cancelButtonProps | 取消按钮属性；根类名使用 Vue 原生 `class` | PopconfirmButtonProps | - |
| showCancel | 是否显示取消按钮 | boolean | true |
| icon | 图标数据；`false` 时不显示。模板组合使用 `#icon` | VNode \| string \| false | ExclamationCircleFilled |
| onConfirm | 点击确认 | (e?: MouseEvent) => void \| Promise | - |
| onCancel | 点击取消 | (e?: MouseEvent) => void | - |
| classNames | 语义化类名（root / container / arrow / icon / title / content） | 对象或函数 | - |
| styles | 语义化样式（同上） | 对象或函数 | - |

> `onConfirm` / `onCancel` 是业务回调 props，支持 `:on-confirm` / `:onConfirm` 等 Vue 绑定；确认回调的返回值用于等待 Promise。状态同步通过 `update:open` / `v-model:open`。

确认同步返回时请求关闭；返回 Promise 时，按钮进入 loading，成功后请求关闭，失败保持面板并通过 Vue 错误处理上报。实际接受关闭后，下次打开使用新的确认会话，旧 Promise 不会关闭新面板；业务请求和定时器仍由调用者在取消及卸载时清理。受控父级拒绝关闭时，当前操作继续。

### 插槽

| 名称 | 说明 |
| --- | --- |
| default | 触发元素（仅 Popconfirm） |
| title / description | 标题 / 描述，优先于同名 prop |
| icon | 图标内容，优先于 icon 数据或默认图标；空槽不渲染包裹 |
| okText / cancelText | 按钮内容，优先于字符串 prop 和 locale |

导出 `PopconfirmSlots`。五个内容槽也适用于 `PopconfirmPurePanel`；空槽不回退，移除槽才恢复 prop、默认图标或 locale。条件槽在当前 render 读取，图标切换保持正文节点与输入状态。内容函数 prop 已直接移除；异步确认等业务回调保留，见 [迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/overlay-content-slots.md)。

### 原生 class/style

原生 `class/style` 作用于浮层根，style 支持字符串、对象和混合数组，优先于语义根样式。PopconfirmPurePanel 转发 root/container/arrow 的 classNames/styles 给静态面板，icon/title/content 给确认正文；原生 style 只作用于面板根，不覆盖 styles.container。

### 事件

| 事件 | 说明 | 参数 |
| --- | --- | --- |
| openChange | 请求改变展开状态；受控时由父级决定是否接受 | `(open: boolean)` |
| update:open | `v-model:open` 同步请求 | `(open: boolean)` |
| popupClick | 确认正文被点击；静态面板同样支持 | `(event: MouseEvent)` |
| afterOpenChange | 开合动画完成 | `(open: boolean)` |

模板使用 `@open-change` / `@popup-click` / `@after-open-change`，支持 `.once` 和监听器数组；JSX / `h()` 使用 `onOpenChange` / `onPopupClick` / `onAfterOpenChange`。旧的 `:on-open-change` / `:on-popup-click` 函数 prop 直接改为事件，不保留兼容通道。`onConfirm` / `onCancel` 业务回调保持原契约。

原生 `class/style` 只作用于浮层根，其他原生 attrs 和事件传给触发元素。撤销受控 `open` 后保留最后接受的值，父级拒绝的更新请求不会成为本地状态。

### Ref

`Popconfirm` 与 `Popover` 同物：`forceAlign` / `nativeElement` / `popupElement`。

### 主题变量

| Token | 说明 | 默认值 |
| --- | --- | --- |
| zIndexPopup | 浮层 z-index | zIndexPopupBase + 60 |

`theme.components.Popconfirm.zIndexPopup` 与现有全局视觉 Token 读取当前主题，支持嵌套、替换和移除，`0` 是有效层级。Popconfirm 与静态面板只消费自己的组件配置；正文中的独立 Popover / Tooltip 仍消费各自配置。内部共享一次层级计算；最终根样式的数值 `zIndex`（含 `0`、数字字符串）优先并同步后代层级，撤除后恢复专用 `zIndex` 或自动层级。条件根样式中的 `undefined`、空字符串及原生 style 的 `false/null/undefined` 释放当前覆盖；`calc/var` 的自动后代层级仍延期。

[静态面板原生 style 迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/overlay-native-styles.md)。


## 基本 (basic)

最简单的用法：`title` + `description` 双通道。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { Button, Popconfirm } from '@apollo-design/ui';

const confirm = (e?: MouseEvent) => console.log(e);
const cancel = (e?: MouseEvent) => console.log(e);
</script>

<template>
  <Popconfirm
    title="Delete the task"
    description="Are you sure to delete this task?"
    :on-confirm="confirm"
    :on-cancel="cancel"
    ok-text="Yes"
    cancel-text="No"
  >
    <Button danger>Delete</Button>
  </Popconfirm>
</template>
```

## 定制按钮文案 (locale)

`okText` / `cancelText` 为空时回退到 locale 的 OK / Cancel。

### locale.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 locale demo：okText / cancelText 定制
import { Button, Popconfirm } from '@apollo-design/ui';
</script>

<template>
  <Popconfirm
    title="Delete the task"
    description="Are you sure to delete this task?"
    ok-text="Yes"
    cancel-text="No"
  >
    <Button danger>Delete</Button>
  </Popconfirm>
</template>
```

## 自定义图标 (icon)

使用原生 `#icon` 组合图标组件与当前内容。槽优先于 icon 数据，包括有意为空；移除槽后恢复默认图标或 icon 数据。静态预览传入 false，移除槽后隐藏图标；正文输入保持。

### icon.vue

```vue
<script setup lang="ts">
import { QuestionCircleOutlined } from '@apollo-design/icons';
import { Button, Input, Popconfirm, PopconfirmPurePanel } from '@apollo-design/ui';
import { ref } from 'vue';

const show = ref(true);
const empty = ref(false);
const count = ref(0);
</script>

<template>
  <div>
    <p style="display: flex; flex-wrap: wrap; gap: 8px">
      <Button @click="show = !show">Toggle native icon slot</Button>
      <Button @click="empty = !empty">Empty native icon slot</Button>
      <Button @click="count++">Update native icon</Button>
    </p>
    <Popconfirm title="Delete the task" description="Are you sure to delete this task?">
      <Button danger>Delete with native icon</Button>
      <template v-if="show" #icon>
        <template v-if="!empty"><QuestionCircleOutlined style="color: red" /><span>{{ count }}</span></template>
      </template>
    </Popconfirm>
    <PopconfirmPurePanel data-native-icon-panel title="Icon preview" :icon="false">
      <template v-if="show" #icon>
        <template v-if="!empty"><QuestionCircleOutlined style="color: red" /><span data-native-icon-count>{{ count }}</span></template>
      </template>
      <template #description><Input aria-label="Native icon note" /></template>
    </PopconfirmPurePanel>
  </div>
</template>
```

## Promise 关闭 (promise)

`onConfirm` 返回 Promise 时按钮进 loading，resolve 后才关闭。

### promise.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 promise demo：onConfirm 返回 Promise，resolve 后才关闭
import { Button, Popconfirm } from '@apollo-design/ui';
import { onBeforeUnmount } from 'vue';

const timers = new Set<ReturnType<typeof setTimeout>>();
const confirm = () =>
  new Promise((resolve) => {
    const timer = setTimeout(() => {
      timers.delete(timer);
      resolve(null);
    }, 3000);
    timers.add(timer);
  });
onBeforeUnmount(() => {
  for (const timer of timers) clearTimeout(timer);
});
</script>

<template>
  <Popconfirm
    title="Title"
    description="Open Popconfirm with Promise"
    :on-confirm="confirm"
    @open-change="() => console.log('open change')"
  >
    <Button type="primary">Open Popconfirm with Promise</Button>
  </Popconfirm>
</template>
```

## 受控与异步 (async)

通过 `v-model:open` 受控，配合 `okButtonProps.loading` 表达进行中的状态。

### async.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 async demo：受控 open + 异步确认

import { Button, Popconfirm } from '@apollo-design/ui';
import { onBeforeUnmount, ref } from 'vue';

const open = ref(false);
const confirmLoading = ref(false);

const showPopconfirm = () => {
  open.value = true;
};

let timer: ReturnType<typeof setTimeout> | undefined;
let finish: (() => void) | undefined;

const handleOk = (): Promise<void> => {
  confirmLoading.value = true;
  return new Promise((resolve) => {
    finish = resolve;
    timer = setTimeout(() => {
      timer = undefined;
      finish = undefined;
      open.value = false;
      confirmLoading.value = false;
      resolve();
    }, 2000);
  });
};

const handleCancel = () => {
  clearTimeout(timer);
  timer = undefined;
  open.value = false;
  confirmLoading.value = false;
  const resolve = finish;
  finish = undefined;
  resolve?.();
};

onBeforeUnmount(handleCancel);
</script>

<template>
  <Popconfirm
    v-model:open="open"
    title="Title"
    description="Open Popconfirm with async logic"
    :ok-button-props="{ loading: confirmLoading }"
    :on-confirm="handleOk"
    :on-cancel="handleCancel"
  >
    <Button type="primary" @click="showPopconfirm">Open Popconfirm with async logic</Button>
  </Popconfirm>
</template>
```

## 位置 (placement)

支持 12 个方位。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 placement demo（ConfigProvider 的 button 样式改为内联 style）
import { Button, Popconfirm } from '@apollo-design/ui';

const text = 'Are you sure to delete this task?';
const description = 'Delete the task';
const placements = ['topLeft', 'top', 'topRight'] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 4px; justify-content: center">
    <Popconfirm
      v-for="placement in placements"
      :key="placement"
      :placement="placement"
      :title="text"
      :description="description"
      ok-text="Yes"
      cancel-text="No"
    >
      <Button style="width: 80px; margin: 4px">{{ placement }}</Button>
    </Popconfirm>
  </div>
</template>
```

## 条件触发 (dynamic-trigger)

`@open-change` 中可以决定是否接受受控状态更新。

### dynamic-trigger.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 dynamic-trigger demo

import { Button, Popconfirm, Switch } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const condition = ref(true);

const changeOpen = (next: boolean) => {
  if (!condition.value) return;
  open.value = next;
};

const changeCondition = (checked: boolean) => {
  condition.value = checked;
};
</script>

<template>
  <div style="display: flex; align-items: center; gap: 8px">
    <Popconfirm
      :open="open"
      title="Delete the task"
      description="Are you sure to delete this task?"
      @open-change="changeOpen"
    >
      <Button danger>Delete a task</Button>
    </Popconfirm>
    <div>
      Whether directly execute:
      <Switch aria-label="Whether directly execute" :checked="condition" @update:checked="changeCondition" />
    </div>
  </div>
</template>
```

## 自定义面板渲染 (render-panel)

使用原生标题、描述及按钮内容槽；切换、更新和清空后，只有移除槽才恢复 prop / locale。原生字符串 style 与语义根样式按 Vue 规则合并。主题按钮切换当前 `Popconfirm.zIndexPopup`，移除覆盖后恢复默认层级。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 render-panel demo：PurePanel（调试用面板）
import { Button, ConfigProvider, PopconfirmPurePanel } from '@apollo-design/ui';
import { ref } from 'vue';

const show = ref(false);
const empty = ref(false);
const count = ref(0);
const themed = ref(false);
</script>

<template>
  <div>
    <p style="display: flex; flex-wrap: wrap; gap: 8px">
      <Button @click="show = !show">Toggle popconfirm slots</Button>
      <Button @click="empty = !empty">Empty popconfirm slots</Button>
      <Button @click="count++">Update popconfirm slots</Button>
      <Button @click="themed = !themed">Theme z-index: {{ themed ? 2060 : 'default' }}</Button>
    </p>
    <ConfigProvider :theme="themed ? { components: { Popconfirm: { zIndexPopup: 2060 } } } : undefined">
    <PopconfirmPurePanel data-native-popconfirm-panel title="Delete the task" description="Are you sure to delete this task?" ok-text="Confirm" cancel-text="Cancel" style="max-width: 360px" :styles="{ root: { minHeight: '80px' }, arrow: { opacity: 0.6 } }">
      <template v-if="show" #title><strong v-if="!empty">Native confirmation {{ count }}</strong></template>
      <template v-if="show" #description><span v-if="!empty">Current details {{ count }}</span></template>
      <template v-if="show" #okText><b v-if="!empty">Proceed {{ count }}</b></template>
      <template v-if="show" #cancelText><span v-if="!empty">Back {{ count }}</span></template>
    </PopconfirmPurePanel>
    </ConfigProvider>
  </div>
</template>
```

## 语义化结构 (style-class)

语义槽：`root` / `container` / `arrow` / `icon` / `title` / `content`（description 用 `content`）。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo（语义化 classNames / styles）
import { Button, Popconfirm } from '@apollo-design/ui';

const classNames = { root: 'custom-popconfirm', icon: 'custom-icon' };
const styles = { root: { padding: 20 }, icon: { color: 'red' } };
</script>

<template>
  <Popconfirm
    title="Delete the task"
    description="Are you sure to delete this task?"
    :class-names="classNames"
    :styles="styles"
  >
    <Button danger>Delete</Button>
  </Popconfirm>
</template>
```

## 大页面下的浮层 (shift)

浮层在大页面里会自动调整位置（autoAdjustOverflow）。

### shift.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 shift demo：页面滚动后浮层跟随（纯展示，不 scroll 页面）
import { Button, Popconfirm } from '@apollo-design/ui';
</script>

<template>
  <div style="display: flex; align-items: center; justify-content: center; padding: 48px 0">
    <Popconfirm title="Thanks for using apollo-design. Have a nice day !" open>
      <Button type="primary">Scroll The Window</Button>
    </Popconfirm>
  </div>
</template>
```

---

# Popover

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/popover


点击/鼠标移入时弹出气泡卡片。

## 何时使用

- 需要对目标元素做进一步说明时，用带标题/正文的气泡卡片。
- 复用 Tooltip 的触发协议，内容更丰富（标题 + 正文）。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/popover/demo)（12 个，覆盖 antd 的主要用户场景；Segmented 未落地 ⇒
原生 select 替换，见各文件头）。

## API

### Props

继承 [Tooltip](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/tooltip/index.zh-CN.md) 的全部 props，另有：

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 标题数据（`0` 合法）；模板内容使用 `#title` | `TooltipContent`（VNodeChild） | — |
| content | 正文数据（`0` 合法）；模板内容使用 `#content` | `TooltipContent`（VNodeChild） | — |
| classNames / styles | 语义槽 `root / container / arrow / title / content`（含函数式） | — | — |

⚠️ 受控 `open` 时不做 noTitle 压制（antd 口径）：title/content 均空仍会开空浮层。

### 插槽

| 名称 | 说明 |
|---|---|
| default | 触发元素 |
| title / content | 标题 / 正文；存在则覆盖同名 prop，空槽不回退 |

导出 `PopoverSlots`。主组件与 `PopoverPurePanel` 均在当前 render 读取槽，支持条件出现、移除与内容更新。内容函数 prop 已直接移除，见 [迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/overlay-content-slots.md)。

### 原生 class/style

Popover 的原生 `class/style` 作用于浮层根，不传到触发元素。style 接受字符串、对象和混合数组，优先于 `styles.root`，移除后恢复语义值。其他原生 attrs 和监听器沿用 Tooltip 的触发元素落点。PopoverPurePanel 的 attrs、class/style 作用于面板根；不把原生 style 重复应用到 container。分区样式使用 `styles.container/arrow` 与对应 classNames。

根样式的数值层级（含 `0`、数字字符串）与后代 Tooltip/Popover/Popconfirm 的数值上下文同步，按最终样式优先级覆盖专用 `zIndex`。`undefined`、空字符串或原生 style 的 `false/null/undefined` 撤除当前覆盖；`calc/var` 的自动后代层级仍是延期边界，见 Tooltip 的原生样式说明。

### 事件

| 事件 | 载荷 | 说明 |
|---|---|---|
| update:open | `boolean` | `v-model:open`；受控值由调用方决定是否接受 |
| open-change | `boolean` | 与模型同时发送开合提议 |
| after-open-change | `boolean` | 实际开合动画完成 |
| popup-click | `MouseEvent` | 浮层内容的原始点击事件 |

通知统一使用 Vue emits，支持 `.once` 和监听器数组；`h()` 使用 `onOpenChange`、`onAfterOpenChange` 和 `onPopupClick`，不再作为函数 prop 手动调用。导出 `PopoverEmits`。旧 `afterOpenChange` 回调 prop 已直接移除。

### Expose

`forceAlign()`、`nativeElement: HTMLElement | null`、`popupElement: HTMLDivElement | null`（`PopoverRef`）。后两者是当前 DOM 属性，关闭卸载后 `popupElement` 为 `null`。

### 当前配置与主题

主组件和 PopoverPurePanel 消费当前 `ConfigProvider.components.popover` 的类名、语义样式及根样式；不会叠加 `components.tooltip` 的专属配置。PurePanel 支持 `title`、`content`、`color`、`placement`、`prefixCls`、`classNames` 和 `styles`，内容槽契约与主组件相同。

`theme.components.Popover` 支持以下数值 Token；主题替换、嵌套和撤除会更新实际浮层与静态面板，不替换正文输入或焦点。原生和语义样式仍可覆盖对应 CSS 变量。

| Token | 默认值 | 说明 |
|---|---|---|
| titleMinWidth | `177` | 标题最小宽度，px |
| zIndexPopup | 全局 `zIndexPopupBase + 30` | 浮层层级；显式 `zIndex` 和父浮层层叠仍有效 |
| innerPadding | `12` | 内容容器内边距，px |
| titleMarginBottom | `8` | 标题下间距，px |

现存 Tooltip 样式别名 `overlayClassName`、`overlayStyle`、`overlayInnerStyle` 和 `destroyTooltipOnHide` 按继承契约生效，优先使用 `classNames.root`、`styles.root/container` 和 `destroyOnHidden`。线框主题仍为已记录缺口。

## 设计说明

- **职责**：Tooltip / `_internal/trigger.ts` 管浮层生命周期与定位，Popover 管自己的内容、事件、Provider 和 Token（[`历史分析`](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/analysis/popover.md)）。
- 与 antd 的已知差异见组件 README。

[静态面板原生 style 迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/overlay-native-styles.md)。


## arrow (arrow)

箭头可以隐藏、指向中心。

### arrow.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/arrow.tsx（箭头三态：Show / Hide / Center）。

import type { TooltipPlacement } from '@apollo-design/ui';
import { Button, Popover, Segmented } from '@apollo-design/ui';
import { ref } from 'vue';

const text = 'Title';
const arrowMode = ref<'Show' | 'Hide' | 'Center'>('Show');
const btnStyle = { width: '80px' };

const rows: TooltipPlacement[][] = [
  ['topLeft', 'top', 'topRight'],
  ['leftTop', 'left', 'leftBottom', 'rightTop', 'right', 'rightBottom'],
  ['bottomLeft', 'bottom', 'bottomRight'],
];
const mergedArrow = () => {
  if (arrowMode.value === 'Hide') return false;
  if (arrowMode.value === 'Center') return { pointAtCenter: true };
  return true;
};
</script>

<template>
  <div>
    <Segmented v-model:value="arrowMode" :options="['Show', 'Hide', 'Center']" aria-label="arrow mode" style="margin-bottom: 24px" />
    <div style="display: flex; flex-direction: column; align-items: center; row-gap: 16px">
      <div v-for="(row, i) in rows" :key="i" style="display: flex; flex-wrap: wrap; justify-content: center; gap: 4px">
        <Popover v-for="p in row" :key="p" :placement="p" :title="text" :arrow="mergedArrow()">
          <template #content>
            <p>Content</p>
            <p>Content</p>
          </template>
          <Button :style="btnStyle">{{ p }}</Button>
        </Popover>
      </div>
    </div>
  </div>
</template>
```

## arrow-point-at-center (arrow-point-at-center)

设置 `arrow.pointAtCenter` 后，箭头将指向目标元素中心。

### arrow-point-at-center.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/arrow-point-at-center.tsx（12 方向 × 箭头指向中心 + 十字准星）
import { Popover } from '@apollo-design/ui';

const placements = [
  'topLeft',
  'top',
  'topRight',
  'leftTop',
  'left',
  'leftBottom',
  'rightTop',
  'right',
  'rightBottom',
  'bottomLeft',
  'bottom',
  'bottomRight',
] as const;

const itemStyle = {
  width: '120px',
  height: '120px',
  display: 'inline-flex',
  justifyContent: 'center',
  alignItems: 'center',
  border: '1px dashed purple',
  margin: '8px',
};
const boxStyle: Record<string, string> = {
  width: '40px',
  height: '40px',
  backgroundColor: 'deepskyblue',
  position: 'relative',
};
</script>

<template>
  <div style="max-width: 500px">
    <div v-for="p in placements" :key="p" :style="itemStyle">
      <Popover
        :placement="p"
        :content="p"
        :auto-adjust-overflow="false"
        :arrow="{ pointAtCenter: true }"
        force-render
        open
      >
        <div :style="boxStyle" />
      </Popover>
    </div>
  </div>
</template>
```

## basic (basic)

最简单的用法，浮层的大小由内容区域决定。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic.tsx（最简用法）
import { Button, Popover } from '@apollo-design/ui';
</script>

<template>
  <Popover title="Title">
    <template #content>
      <p style="margin: 0">Content</p>
      <p style="margin: 0">Content</p>
    </template>
    <Button type="primary">Hover me</Button>
  </Popover>
</template>
```

## component-token (component-token)

通过当前 ConfigProvider 的 `theme.components.Popover` 定制标题宽度、内边距和标题间距。点击按钮后两个静态面板即时更新。

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, PopoverPurePanel } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const content = ['Content', 'Content'];
const padding = ref(12);
const theme = computed(() => ({
  components: {
    Popover: { titleMinWidth: 200, innerPadding: padding.value, titleMarginBottom: 10 },
  },
}));
</script>

<template>
  <ConfigProvider :theme="theme">
    <Button style="margin-bottom: 16px" @click="padding = padding === 12 ? 20 : 12">Padding: {{ padding }}px</Button>
    <div style="display: flex; flex-wrap: wrap; gap: 16px">
      <PopoverPurePanel title="Title" class="demo-current-popover">
        <template #content>
          <div>
            <p v-for="(c, i) in content" :key="i">{{ c }}</p>
          </div>
        </template>
      </PopoverPurePanel>
      <PopoverPurePanel title="Title" placement="bottomLeft" style="width: 250px; max-width: 100%">
        <template #content>
          <div>
            <p v-for="(c, i) in content" :key="i">{{ c }}</p>
          </div>
        </template>
      </PopoverPurePanel>
    </div>
  </ConfigProvider>
</template>
```

## control (control)

受控关闭。

### control.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/control.tsx（受控 + 点击关闭）

import { Button, Popover } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const hide = () => {
  open.value = false;
};
</script>

<template>
  <Popover
    v-model:open="open"
    title="Title"
    trigger="click"
  >
    <template #content>
      <Button type="link" @click="hide">Close</Button>
    </template>
    <Button type="primary">Click me</Button>
  </Popover>
</template>
```

## hover-with-click (hover-with-click)

同一次操作同时绑定 hover 与 click 触发。

### hover-with-click.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/hover-with-click.tsx（hover 与 click 双触发嵌套）

import { Button, Popover } from '@apollo-design/ui';
import { ref } from 'vue';

const clicked = ref(false);
const hovered = ref(false);

const hide = () => {
  clicked.value = false;
  hovered.value = false;
};
const handleHoverChange = (next: boolean) => {
  hovered.value = next;
  clicked.value = false;
};
const handleClickChange = (next: boolean) => {
  hovered.value = false;
  clicked.value = next;
};
</script>

<template>
  <Popover
    title="Hover title"
    trigger="hover"
    :open="hovered"
    @open-change="handleHoverChange"
  >
    <template #content>
      <div>This is hover content.</div>
    </template>
    <Popover
      title="Click title"
      trigger="click"
      :open="clicked"
      @open-change="handleClickChange"
    >
      <template #content>
        <div>This is click content.</div>
        <Button type="link" @click="hide">Close</Button>
      </template>
      <Button>Hover and click</Button>
    </Popover>
  </Popover>
</template>
```

## placement (placement)

位置有十二个方向。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/placement.tsx（12 方向）。antd 用 ConfigProvider button 统一宽度，
// 本仓 D25：直接给按钮行内样式（语义等价）。
import { Button, Popover } from '@apollo-design/ui';
import type { CSSProperties } from 'vue';

const text = 'Title';

const btnStyle = { width: '80px' };
const rowStyle: CSSProperties = {
  display: 'flex',
  flexWrap: 'wrap',
  justifyContent: 'center',
  gap: '8px',
};
</script>

<template>
  <div style="display: flex; flex-direction: column; align-items: center; row-gap: 16px">
    <div :style="rowStyle">
      <Popover v-for="p in ['topLeft', 'top', 'topRight']" :key="p" :placement="p" :title="text">
        <template #content>
          <p>Content</p>
          <p>Content</p>
        </template>
        <Button :style="btnStyle">{{ p }}</Button>
      </Popover>
    </div>
    <div :style="rowStyle">
      <Popover v-for="p in ['leftTop', 'left', 'leftBottom', 'rightTop', 'right', 'rightBottom']" :key="p" :placement="p" :title="text">
        <template #content>
          <p>Content</p>
          <p>Content</p>
        </template>
        <Button :style="btnStyle">{{ p }}</Button>
      </Popover>
    </div>
    <div :style="rowStyle">
      <Popover v-for="p in ['bottomLeft', 'bottom', 'bottomRight']" :key="p" :placement="p" :title="text">
        <template #content>
          <p>Content</p>
          <p>Content</p>
        </template>
        <Button :style="btnStyle">{{ p }}</Button>
      </Popover>
    </div>
  </div>
</template>
```

## render-panel (render-panel)

使用 PurePanel 渲染静态气泡卡片。标题槽支持条件出现、更新和有意为空，切换标题时正文输入保持。原生字符串 style 与语义根样式按 Vue 规则合并。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/render-panel.tsx（PurePanel 静态面板）
import { Button, Input, PopoverPurePanel } from '@apollo-design/ui';
import { ref } from 'vue';

const content = ['Content', 'Content'];
const show = ref(false);
const empty = ref(false);
const count = ref(0);
</script>

<template>
  <div>
    <p style="display: flex; flex-wrap: wrap; gap: 8px">
      <Button @click="show = !show">Toggle popover title</Button>
      <Button @click="empty = !empty">Empty popover title</Button>
      <Button @click="count++">Update popover title</Button>
    </p>
    <div style="display: flex; flex-wrap: wrap; gap: 16px">
      <PopoverPurePanel title="Title">
        <template #content>
          <div>
            <p v-for="(c, i) in content" :key="i">{{ c }}</p>
          </div>
        </template>
      </PopoverPurePanel>
      <PopoverPurePanel
        data-native-popover-panel
        title="Title"
        placement="bottomLeft"
        style="width: 250px; max-width: 100%"
      >
        <template v-if="show" #title>
          <strong v-if="!empty">Native popover {{ count }}</strong>
        </template>
        <template #content>
          <div>
            <p v-for="(c, i) in content" :key="i">{{ c }}</p>
            <Input aria-label="Popover panel note" />
          </div>
        </template>
      </PopoverPurePanel>
    </div>
  </div>
</template>
```

## shift (shift)

浮层随窗口滚动跟随目标元素。示例在独立视口内滚动，不会带动外层文档。

### shift.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/shift.tsx（滚动容器：窗口滚动后浮层跟随）

import { Button, Popover } from '@apollo-design/ui';
import { onMounted } from 'vue';

onMounted(() => {
  window.scrollTo({
    top: document.documentElement.clientHeight,
    left: document.documentElement.clientWidth,
    behavior: 'instant',
  });
});

const style = {
  width: '300vw',
  height: '300vh',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center',
};
</script>

<template>
  <div :style="style">
    <Popover title="Title" content="Thanks for using apollo. Have a nice day !" open>
      <Button type="primary">Scroll The Window</Button>
    </Popover>
  </div>
</template>
```

## style-class (style-class)

使用 styles 定制容器与内容，支持对象与函数两种形态。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx（semantic styles 的对象与函数两种形态）
import { Button, Popover, Tooltip } from '@apollo-design/ui';
import { ref } from 'vue';

const highLayer = ref(true);

const styles = {
  container: {
    background: '#eee',
    boxShadow: 'inset 5px 5px 3px #fff, inset -5px -5px 3px #ddd, 0 0 3px rgba(0,0,0,0.2)',
  },
  content: {
    color: '#262626',
  },
};

const stylesFn = (info: { props: { arrow?: unknown } }) => {
  if (!info.props.arrow) {
    return {
      container: {
        backgroundColor: 'rgba(53, 71, 125, 0.8)',
        padding: '12px',
        borderRadius: '4px',
      },
      content: {
        color: '#fff',
      },
    };
  }
  return {};
};
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 12px">
    <Popover content="Object text" :styles="styles" :arrow="false">
      <Button>Object Style</Button>
    </Popover>
    <Popover content="Function text" :styles="stylesFn" :arrow="false">
      <Button type="primary">Function Style</Button>
    </Popover>
    <Popover class="demo-layer-popover" :style="highLayer && { zIndex: 2500 }">
      <Button>Nested layers</Button>
      <template #content>
        <Tooltip class="demo-layer-tooltip" title="The nested hint follows the current popup layer.">
          <Button @click="highLayer = !highLayer">Popup layer: {{ highLayer ? '2500' : 'default' }}</Button>
        </Tooltip>
      </template>
    </Popover>
  </div>
</template>
```

## triggerType (triggerType)

鼠标移入、聚集、点击。

### triggerType.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/triggerType.tsx（hover / focus / click 三种触发）
import { Button, Popover, Space } from '@apollo-design/ui';

const content = ['Content', 'Content'];
</script>

<template>
  <Space wrap>
    <Popover v-for="t in ['hover', 'focus', 'click']" :key="t" title="Title" :trigger="t">
      <template #content>
        <div>
          <p v-for="(c, i) in content" :key="i">{{ c }}</p>
        </div>
      </template>
      <Button>{{ (t[0] ?? '').toUpperCase() + t.slice(1) }} me</Button>
    </Popover>
  </Space>
</template>
```

## wireframe (wireframe)

wireframe 主题态不支持（D84），以默认主题渲染。

### wireframe.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/wireframe.tsx（PurePanel 静态面板 ×2）。
// ⚠️ wireframe 主题态不支持（D84）⇒ 以默认主题渲染（结构一致，登记差异）。
import { PopoverPurePanel } from '@apollo-design/ui';

const content = ['Content', 'Content'];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <PopoverPurePanel title="Title">
      <template #content>
        <div>
          <p v-for="(c, i) in content" :key="i">{{ c }}</p>
        </div>
      </template>
    </PopoverPurePanel>
    <PopoverPurePanel title="Title" placement="bottomLeft" style="width: 250px; max-width: 100%">
      <template #content>
        <div>
          <p v-for="(c, i) in content" :key="i">{{ c }}</p>
        </div>
      </template>
    </PopoverPurePanel>
  </div>
</template>
```

---

# Progress

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/progress


展示操作当前的进度。

## 何时使用

- 需要准确展示当前进度（上传、加载、步骤完成度等）。
- 支持线形 / 圆环 / 仪表盘三种形态，以及分段进度。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/progress/demo)（17 个，覆盖 antd 的主要用户场景）。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 形态 | `'line' \| 'circle' \| 'dashboard'` | `'line'` |
| percent | 百分比 | `number` | `0` |
| format | 内容格式（fn prop） | `(percent?, successPercent?) => VNodeChild` | `${n}%` |
| status | 状态 | `'normal' \| 'exception' \| 'active' \| 'success'` | —（percent>=100 自动 success） |
| showInfo | 显示指示文本 | `boolean` | `true` |
| strokeColor | 进度色（支持渐变对象） | `string \| string[] \| ProgressGradient` | — |
| railColor | 轨道色 | `string` | — |
| trailColor | ⚠️ 已废弃（用 `railColor`） | `string` | — |
| strokeLinecap | 端点形状 | `'round' \| 'butt' \| 'square'` | `'round'` |
| strokeWidth | 描边宽（line ⇒ 轨道高；circle ⇒ 描边） | `number` | line 8 / circle max(6, 3/宽×100) |
| size | 尺寸（预设/数字/[w,h]/对象） | `'medium' \| 'middle' \| 'small' \| 'default' \| number \| [number \| string, number] \| { width?: number; height?: number }` | `'medium'` |
| width | ⚠️ 已废弃（用 `size`） | `number` | — |
| success | 成功分段 | `{ percent?, strokeColor? }` | — |
| steps | 分段数 | `number \| { count, gap }` | — |
| gapDegree / gapPlacement | 仪表盘缺口（`gapPosition` 已废弃） | `number` / `'top' \| 'bottom' \| 'start' \| 'end'` | dashboard 75 / `'bottom'` |
| percentPosition | 指示文本位置 | `{ align?: 'start'\|'center'\|'end'; type?: 'inner'\|'outer' }` | `{ align: 'end', type: 'outer' }` |
| rounding | 分段取整函数 | `(step: number) => number` | `Math.round` |
| aria-label / aria-labelledby | 无障碍标签 | `string` | — |

> ⚠️ deprecated：`width` → `size`、`trailColor` → `railColor`、`gapPosition` → `gapPlacement`、
> `size="default"` → `size="medium"`（均带告警）。

### 语义面（classNames / styles）

`root` / `body` / `rail` / `track` / `indicator`（对象式与函数式 `({ props }) => …`）。

`rail` 指向线形轨道或连续圆环的 SVG 轨道；分段项使用 `track`，没有独立的 rail 节点。
圆环的 rail 样式直接落在 SVG 元素上。函数式语义配置读取当前 `{ props }`。

线形 size 中的数值宽度按 px 输出，数值、数值 tuple 或对象可设置对应宽度和轨道高度；非正宽度自适应。
`showInfo` 显示的指示文本可以使 body 高于轨道，size 的高度约束轨道。
tuple 宽度也支持 CSS 长度，例如 `['65%', 12]`；线形分段的 tuple 宽度约束每一段。
circle/dashboard 支持数字和预设尺寸，显式 `size` 优先于现存已废弃的 `width`。
保留 `middle`，同时支持文档默认值 `medium`。

`steps.gap` 控制 circle/dashboard 分段间距；`rounding` 控制线形分段取整。
`strokeColor` 数组为线形分段逐项设色，其他形态读取第一个颜色。
渐变接受 `from`/`to` 或百分比站点，`direction` 控制线形渐变方向；圆环站点按百分比排序。

`percentPosition` 替换或移除时，指示内容的宿主、对齐和亮色类同步更新。
`format` 保留为领域数值格式化回调，接收归一化后的进度值和成功进度值，可以返回完整 Vue 内容。
组件没有公开插槽、自有事件、v-model 或 expose 方法。

纯线内嵌文本根据当前不透明单色轨道选择可读的黑/白前景，包含主题色和状态色；
显式 `styles.indicator.color` 仍优先。自定义渐变、透明色或覆盖 track 背景时由作者配对文本颜色。
此处直接修正开发阶段亮色轨道默认对比度不足，没有兼容开关和弃用期。

Vue 原生 `class`、字符串/对象/数组 `style`、DOM attrs 与监听器落在根 progressbar，
每次 DOM 事件只触发一次监听。样式优先级依次为主题变量、Provider `styles`、
Provider `style`、组件 `styles`、原生根 `style`，语义类名合并。
ConfigProvider 的 `components.progress` 消费 `className`、`style`、`classNames`、`styles`，
支持整体替换和移除，并读取当前前缀与方向。

现有六个组件 Token 从 `theme.components.Progress` 消费：`circleTextColor`、`defaultColor`、
`remainingColor`、`lineBorderRadius`、`circleTextFontSize`、`circleIconFontSize`。
`lineBorderRadius` 数字使用 px，其他值为 CSS 字符串。当前主题别名与嵌套覆盖在 SSR 和动态更新时生效。
圆环默认成功段使用当前主题成功色，显式 `success.strokeColor` 优先。

实际 progressbar 的 `aria-valuenow` 优先读取 success.percent，否则读取 percent；
保留有限小数，限制到 0–100，非有限输入按 0。内部无障碍值保持权威，
原生 attrs 的同名值不会覆盖它。可访问名称通过 aria-label / aria-labelledby 提供。
status 的既有整数推导与显式 normal 状态保持原规则。

## 设计说明

- **SVG 圆环内核自研**（H5：不依赖 `@rc-component/progress`）：dasharray/dashoffset
  数学从 antd 实测 DOM 逐值反推（round 圆头修正、gap 旋转、steps 分段）。
- **渐变圆环**（plain object strokeColor）走 mask + foreignObject 的 conic 方案（PtgCircle 语义）。
- **≤20px 圆环**：indicator 经 Tooltip 展示（title 插槽）。
- **Token 6 个**：circleTextColor / defaultColor / remainingColor / lineBorderRadius /
  circleTextFontSize / circleIconFontSize。
- **线性渐变变量** `--progress-line-stroke-color` 无组件前缀（antd 产物逐字）。


## circle (circle)

圆环进度条（exception/success 形态）。

### circle.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/circle.tsx
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex gap="small" wrap>
    <Progress type="circle" :percent="75" />
    <Progress type="circle" :percent="70" status="exception" />
    <Progress type="circle" :percent="100" />
  </Flex>
</template>
```

## circle-micro (circle-micro)

微型圆环（≤20px，indicator 经 Tooltip 展示）。

### circle-micro.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/circle-micro.tsx（≤20px：indicator 经 Tooltip 展示）
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex align="center" gap="small">
    <Progress
      type="circle"
      rail-color="#e6f4ff"
      :percent="60"
      :stroke-width="20"
      :size="14"
      :format="(n?: number) => `In progress, ${n}% complete`"
    />
    <span>Code release</span>
  </Flex>
</template>
```

## circle-mini (circle-mini)

小号圆环进度条（`size` 数字）。

### circle-mini.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/circle-mini.tsx
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex wrap gap="small">
    <Progress type="circle" :percent="30" :size="80" />
    <Progress type="circle" :percent="70" :size="80" status="exception" />
    <Progress type="circle" :percent="100" :size="80" />
  </Flex>
</template>
```

## circle-steps (circle-steps)

圆环分段（circle-steps）。

### circle-steps.vue

```vue
<script setup lang="ts">
// Slider 调整分段数量与间距。
import { Flex, Progress, Slider } from '@apollo-design/ui';
import { ref } from 'vue';

const stepsCount = ref<number>(5);
const stepsGap = ref<number>(7);
</script>

<template>
  <div>
    <p>Custom count:</p>
    <Slider v-model:value="stepsCount" :min="2" :max="10" aria-label-for-handle="steps count" />
    <p>Custom gap:</p>
    <Slider v-model:value="stepsGap" :step="4" :min="0" :max="40" aria-label-for-handle="steps gap" />
    <Flex wrap gap="medium" style="margin-top: 16px">
      <Progress
        type="dashboard"
        :steps="8"
        :percent="50"
        rail-color="var(--apollo-color-fill-secondary)"
        :stroke-width="20"
      />
      <Progress
        type="circle"
        :percent="100"
        :steps="{ count: stepsCount, gap: stepsGap }"
        rail-color="var(--apollo-color-fill-secondary)"
        :stroke-width="20"
      />
    </Flex>
  </div>
</template>
```

## dashboard (dashboard)

仪表盘（`gapDegree` / `gapPlacement` 可调）。

### dashboard.vue

```vue
<script setup lang="ts">
// 用本库的 InputNumber 与 Segmented 调整仪表盘缺口。
import { Flex, InputNumber, Progress, Segmented } from '@apollo-design/ui';
import { ref } from 'vue';

const gapDegree = ref<number>(50);
const gapPlacement = ref<'start' | 'end' | 'top' | 'bottom'>('bottom');
</script>

<template>
  <Flex vertical gap="large">
    <div>
      gapDegree:
      <InputNumber v-model:value="gapDegree" :min="0" :max="360" :step="50" aria-label="gapDegree" style="width: 100px" />
    </div>
    <div>
      gapPlacement:
      <Segmented :value="gapPlacement" :options="['start', 'end', 'top', 'bottom']" aria-label="gapPlacement" @update:value="next => { if (next === 'start' || next === 'end' || next === 'top' || next === 'bottom') gapPlacement = next; }" />
    </div>
    <Progress type="dashboard" :gap-degree="gapDegree" :percent="30" :gap-placement="gapPlacement" />
  </Flex>
</template>
```

## dynamic (dynamic)

动态改变进度值。

### dynamic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/dynamic.tsx
import { MinusOutlined, PlusOutlined } from '@apollo-design/icons';
import { Button, Flex, Progress, SpaceCompact } from '@apollo-design/ui';
import { ref } from 'vue';

const percent = ref<number>(0);

const increase = () => {
  percent.value = Math.min(100, percent.value + 10);
};
const decline = () => {
  percent.value = Math.max(0, percent.value - 10);
};
</script>

<template>
  <Flex vertical gap="small">
    <Flex vertical gap="small">
      <Progress :percent="percent" type="line" />
      <Progress :percent="percent" type="circle" />
    </Flex>
    <SpaceCompact>
      <Button aria-label="减少进度" @click="decline"><MinusOutlined /></Button>
      <Button aria-label="增加进度" @click="increase"><PlusOutlined /></Button>
    </SpaceCompact>
  </Flex>
</template>
```

## format (format)

`format` 自定义 indicator 内容。

### format.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/format.tsx（format 为 fn prop）
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex gap="small" wrap>
    <Progress type="circle" :percent="75" :format="(p?: number) => `${p} Days`" />
    <Progress type="circle" :percent="100" :format="() => 'Done'" />
  </Flex>
</template>
```

## gradient-line (gradient-line)

渐变色进度条（线性多键 / from-to / conic 圆环）。

### gradient-line.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/gradient-line.tsx

import type { ProgressProps } from '@apollo-design/ui';
import { Flex, Progress } from '@apollo-design/ui';

const twoColors: ProgressProps['strokeColor'] = {
  '0%': '#108ee9',
  '100%': '#87d068',
};

const conicColors: ProgressProps['strokeColor'] = {
  '0%': '#87d068',
  '50%': '#ffe58f',
  '100%': '#ffccc7',
};
</script>

<template>
  <Flex vertical gap="medium">
    <Progress :percent="99.9" :stroke-color="twoColors" />
    <Progress :percent="50" status="active" :stroke-color="{ from: '#108ee9', to: '#87d068' }" />
    <Flex gap="small" wrap>
      <Progress type="circle" :percent="90" :stroke-color="twoColors" />
      <Progress type="circle" :percent="100" :stroke-color="twoColors" />
      <Progress type="circle" :percent="93" :stroke-color="conicColors" />
    </Flex>
    <Flex gap="small" wrap>
      <Progress type="dashboard" :percent="90" :stroke-color="twoColors" />
      <Progress type="dashboard" :percent="100" :stroke-color="twoColors" />
      <Progress type="dashboard" :percent="93" :stroke-color="conicColors" />
    </Flex>
  </Flex>
</template>
```

## info-position (info-position)

`percentPosition` 控制 indicator 位置（inner/outer × start/center/end）。

### info-position.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/info-position.tsx
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex gap="small" vertical class="demo-progress-info-position">
    <Progress :percent="0" :percent-position="{ align: 'center', type: 'inner' }" :size="[200, 20]" stroke-color="#E6F4FF" />
    <Progress :percent="10" :percent-position="{ align: 'center', type: 'inner' }" :size="[300, 20]" />
    <Progress :percent="50" :percent-position="{ align: 'start', type: 'inner' }" :size="[300, 20]" stroke-color="#B7EB8F" />
    <Progress :percent="60" :percent-position="{ align: 'end', type: 'inner' }" :size="[300, 20]" stroke-color="#001342" />
    <Progress :percent="100" :percent-position="{ align: 'center', type: 'inner' }" :size="[400, 20]" />
    <Progress :percent="60" :percent-position="{ align: 'start', type: 'outer' }" />
    <Progress :percent="100" :percent-position="{ align: 'start', type: 'outer' }" />
    <Progress :percent="60" :percent-position="{ align: 'center', type: 'outer' }" size="small" />
    <Progress :percent="100" :percent-position="{ align: 'center', type: 'outer' }" />
  </Flex>
</template>

<style scoped>
.demo-progress-info-position :deep(.apollo-progress-line) { max-width: 100%; }
</style>
```

## line (line)

普通的线形进度条（status 四态 + 隐藏 indicator）。

### line.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/line.tsx
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex gap="small" vertical>
    <Progress :percent="30" />
    <Progress :percent="50" status="active" />
    <Progress :percent="70" status="exception" />
    <Progress :percent="100" />
    <Progress :percent="50" :show-info="false" />
  </Flex>
</template>
```

## line-mini (line-mini)

小号线形进度条。

### line-mini.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/line-mini.tsx
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="small" style="width: 180px">
    <Progress :percent="30" size="small" />
    <Progress :percent="50" size="small" status="active" />
    <Progress :percent="70" size="small" status="exception" />
    <Progress :percent="100" size="small" />
  </Flex>
</template>
```

## linecap (linecap)

`strokeLinecap="butt"` 方角。

### linecap.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/linecap.tsx
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="small">
    <Progress stroke-linecap="butt" :percent="75" />
    <Flex wrap gap="small">
      <Progress stroke-linecap="butt" type="circle" :percent="75" />
      <Progress stroke-linecap="butt" type="dashboard" :percent="75" />
    </Flex>
  </Flex>
</template>
```

## segment (segment)

`success` 分段（正确的部分显示为绿色）。

### segment.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/segment.tsx（success 分段）
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex gap="small" vertical>
    <Progress :percent="60" :success="{ percent: 30 }" title="3 done / 3 in progress / 4 to do" />
    <Flex gap="small" wrap>
      <Progress :percent="60" :success="{ percent: 30 }" type="circle" />
      <Progress :percent="60" :success="{ percent: 30 }" type="dashboard" />
    </Flex>
  </Flex>
</template>
```

## semantic (semantic)

语义化 `classNames` / `styles`（函数式变体按 percent 派生色相）。

### semantic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/semantic.tsx（语义面函数式 styles）

import type { ProgressProps } from '@apollo-design/ui';
import { Flex, Progress } from '@apollo-design/ui';

const classNames: ProgressProps['classNames'] = {
  root: 'demo-progress-root',
  rail: 'demo-progress-rail',
  track: 'demo-progress-track',
};

const stylesFn: ProgressProps['styles'] = (info) => {
  const percent = info?.props?.percent ?? 0;
  const hue = 200 - (200 * percent) / 100;
  return {
    track: {
      backgroundImage: `linear-gradient(to right, hsla(${hue}, 85%, 65%, 1), hsla(${hue + 30}, 90%, 55%, 0.95))`,
      borderRadius: '8px',
      transition: 'all 0.3s ease',
    },
    rail: {
      backgroundColor: 'var(--apollo-color-fill-secondary)',
      borderRadius: '8px',
    },
  };
};
</script>

<template>
  <Flex gap="small" vertical style="width: 300px; max-width: 100%">
    <Progress :percent="50" :class-names="classNames" :styles="stylesFn" />
    <Progress :percent="80" :class-names="classNames" :styles="stylesFn" />
    <Progress :percent="100" :class-names="classNames" :styles="stylesFn" />
  </Flex>
</template>
```

## size (size)

`size` 全形态（预设 / 数字 / 数组）。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/size.tsx
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="medium">
    <Flex vertical gap="small" style="width: 300px; max-width: 100%">
      <Progress :percent="50" />
      <Progress :percent="50" size="small" />
      <Progress :percent="50" :size="[300, 20]" />
    </Flex>
    <Flex align="center" wrap gap="30px">
      <Progress type="circle" :percent="50" />
      <Progress type="circle" :percent="50" size="small" />
      <Progress type="circle" :percent="50" :size="20" />
    </Flex>
    <Flex align="center" wrap gap="30px">
      <Progress type="dashboard" :percent="50" />
      <Progress type="dashboard" :percent="50" size="small" />
      <Progress type="dashboard" :percent="50" :size="20" />
    </Flex>
    <Flex align="center" wrap gap="30px">
      <Progress :steps="3" :percent="50" />
      <Progress :steps="3" :percent="50" size="small" />
      <Progress :steps="3" :percent="50" :size="20" />
      <Progress :steps="3" :percent="50" :size="[20, 30]" />
    </Flex>
  </Flex>
</template>
```

## steps (steps)

分段进度条（`steps` + `strokeColor` 数组）。

### steps.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/steps.tsx（antd colors green[6]=#52c41a / red[5]=#ff7875）
import { Flex, Progress } from '@apollo-design/ui';
</script>

<template>
  <Flex gap="small" vertical>
    <Progress :percent="50" :steps="3" />
    <Progress :percent="30" :steps="5" />
    <Progress :percent="100" :steps="5" size="small" stroke-color="#52c41a" />
    <Progress :percent="60" :steps="5" :stroke-color="['#52c41a', '#52c41a', '#ff7875']" />
  </Flex>
</template>
```

## style-class (style-class)

语义化 `classNames` / `styles`（对象式）。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx（对象式语义面）

import type { ProgressProps } from '@apollo-design/ui';
import { Flex, Progress } from '@apollo-design/ui';

const classNames: ProgressProps['classNames'] = {
  root: 'demo-sc-root',
  indicator: 'demo-sc-indicator',
};

const styles: ProgressProps['styles'] = {
  rail: { backgroundColor: 'var(--apollo-color-fill-secondary)' },
  track: { borderRadius: '8px' },
};
</script>

<template>
  <Flex gap="small" vertical style="width: 300px; max-width: 100%">
    <Progress :percent="50" :class-names="classNames" :styles="styles" />
  </Flex>
</template>
```

---

# QRCode

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/qr-code


将文本或分段内容编码为二维码，支持canvas和svg。status由调用者控制，组件不管理网络请求或v-model。

## 代码演示

见[demo/](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/qr-code/demo)的5个实际示例：basic、custom、status、svg、component-token。

## API

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 二维码内容；缺省或空字符串不渲染，并在开发模式告警 | string \| string[] | — |
| type | 绘制形态 | canvas \| svg | canvas |
| size | 正有限像素尺寸，同时定义逻辑画布；非法值回退160 | number | 160 |
| icon | 中心图标URL；canvas等待图片载入再挖空绘制 | string | — |
| iconSize | 正有限图标尺寸，宽高可分别配置；缺省/非法轴回退40 | number \| { width?, height? } | 40 |
| color | 图像前景色；默认取默认主题colorText，保持中性图像对比度 | string | 默认主题colorText |
| bgColor | 显式设置图像及宿主背景；缺省图像像素透明、宿主白色；transparent显式选择透明宿主 | string | — |
| errorLevel | 纠错级别；L与图标同时使用有开发提示 | L \| M \| Q \| H | M |
| status | active无覆盖层，其余状态显示覆盖层 | active \| expired \| loading \| scanned | active |
| bordered | 显示边框 | boolean | true |
| marginSize | 静默区模块数，向下取整并限制非负；非有限值回退0 | number | 0 |
| boostLevel | 编码器允许时提高纠错级别 | boolean | 编码器默认值 |
| title | 两种图像形态的可访问名称，SVG还输出title节点 | string | QR code |
| prefixCls | 当前类名前缀；匹配的静态CSS需提前载入 | string | apollo-qrcode |
| classNames / styles | root与cover的语义class/CSS样式；原生class/style留在根且优先 | { root?, cover? } | — |

### Slots

| 名称 | 作用域 | 说明 |
|---|---|---|
| status | { status, locale, refresh } | 完整原生状态内容；非active时在render读取。存在的空槽不回退；refresh始终为发出事件的稳定操作，不以监听器存在性控制内容 |

```vue
<QrCode value="https://apollo.design" status="expired" @refresh="reload">
  <template #status="{ status, locale, refresh }">
    <span>{{ status }}</span>
    <button type="button" @click="refresh">{{ locale.refresh }}</button>
  </template>
</QrCode>
```

### Emits / Expose

refresh不带参数；可以用@refresh或Vue的onRefresh监听，动态增删与.once有效。组件没有v-model。

nativeElement为HTMLDivElement或null；未渲染/卸载时为空。status切换保留根和同形态图像节点；非active状态之间保留状态槽中的原生编辑器。canvas↔svg更换图像节点，根/状态槽保持。

### Provider、样式与主题

components.qrcode支持className、style、classNames、styles；当前locale.QRCode作用于默认状态和槽scope。替换或移除配置随Vue更新生效。

唯一Component Token为QRCodeCoverBackgroundColor，默认从当前colorBgContainer取96%不透明度。theme.components.QRCode可覆盖，显式根变量--apollo-qrcode-cover-background-color优先。暗色/紧凑模式改变界面与覆盖层；默认图像保留黑白对比度。显式透明背景或自定义前景/背景时，调用者负责扫描所需对比度。

原生字符串、数组和对象style都只作用于根。图像填充根的内部区域并保持比例；size控制逻辑缓冲，DPR用于实际canvas分辨率。不要用根宽高充当图像节点的内联样式。

### 编码与边界

编码使用保留版权的Nayuki qrcodegen（MIT）及既有工具；合法输入的矩阵、路径、纠错和图标挖空算法不变。内容须符合QR标准容量限制。canvas导出仍受浏览器跨域图片安全限制；本组件不新增下载、扫描器或请求模型。


## 基本 (basic)

默认 160px、带边框、canvas 渲染。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { QrCode } from '@apollo-design/ui';
</script>

<template>
  <QrCode value="https://apollo.design" />
</template>
```

## 自定义颜色与尺寸 (custom)

`color` 前景色 / `bg-color` 背景色 / `size` 尺寸。

### custom.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 customColor / customSize demo
import { QrCode } from '@apollo-design/ui';
</script>

<template>
  <QrCode value="https://apollo.design" color="#1677ff" style="margin-bottom: 16px" />
  <QrCode value="https://apollo.design" color="#1677ff" bg-color="#f0f5ff" :size="96" bordered />
</template>
```

## 状态覆盖层 (status)

status由调用者控制。过期时通过@refresh重新加载，每次加载均会再次到期并清理定时器。#status使用单对象作用域{ status, locale, refresh }，保留全部原生节点；存在的空槽抑制默认内容，active不消费状态槽。

### status.vue

```vue
<script setup lang="ts">
import type { QrcodeStatusType } from '@apollo-design/ui';
import { Button, Checkbox, Input, QrCode } from '@apollo-design/ui';
import { onMounted, onUnmounted, ref } from 'vue';

const status = ref<QrcodeStatusType>('loading');
const custom = ref(true),
  empty = ref(false);
const draft = ref('Current status draft');
let timer: ReturnType<typeof setTimeout> | undefined;
function select(next: QrcodeStatusType) {
  clearTimeout(timer);
  timer = undefined;
  status.value = next;
  if (next === 'loading')
    timer = setTimeout(() => {
      status.value = 'expired';
    }, 1000);
}
function refresh() {
  select('loading');
}
onMounted(refresh);
onUnmounted(() => clearTimeout(timer));
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 16px">
    <Button @click="select('active')">Active</Button>
    <Button @click="select('loading')">Loading</Button>
    <Button @click="select('expired')">Expired</Button>
    <Button @click="select('scanned')">Scanned</Button>
    <Checkbox v-model:checked="custom">Custom status</Checkbox>
    <Checkbox v-model:checked="empty">Empty status</Checkbox>
  </div>
  <div style="display: flex; flex-wrap: wrap; gap: 24px">
    <QrCode value="https://apollo.design" title="Default status access" :status="status" @refresh="refresh" />
    <QrCode value="https://apollo.design/status" title="Custom status access" :status="status" @refresh="refresh">
      <template v-if="custom" #status="{ status: current, locale, refresh: requestRefresh }">
        <template v-if="!empty">
          <span v-if="false">Conditional first node</span>
          <Input v-model:value="draft" aria-label="QR status draft" style="width: 112px; max-width: 100%" />
          <output aria-label="QR current status">{{ current }}</output>
          <Button v-if="requestRefresh" size="small" @click="requestRefresh">{{ locale.refresh }}</Button>
        </template>
      </template>
    </QrCode>
  </div>
</template>
```

## SVG 渲染 (svg)

`type="svg"` 输出矢量图形（SSR 友好、无损缩放）；path 与 canvas 像素来自同一矩阵。

### svg.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 type=svg demo（可无损缩放 / SSR 友好）
import { QrCode } from '@apollo-design/ui';
</script>

<template>
  <QrCode value="https://apollo.design" type="svg" />
</template>
```

## 动态遮罩 Token (component-token)

QRCodeCoverBackgroundColor作用于实际遮罩。移除与恢复局部主题保留原生状态槽、输入值和节点；根CSS变量可显式覆盖该Token。

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, Input, QrCode } from '@apollo-design/ui';
import { ref } from 'vue';

const themed = ref(true);
const draft = ref('Native token draft');
</script>

<template>
  <Button @click="themed = !themed">切换 QRCode 主题</Button>
  <ConfigProvider :theme="themed ? { components: { QRCode: { QRCodeCoverBackgroundColor: '#e8f4ec' } } } : undefined">
    <QrCode value="https://apollo.design/token" title="Themed access" status="scanned" :styles="themed ? { cover: { color: '#1f1f1f' } } : undefined" style="margin-top: 16px">
      <template #status>
        <strong>Current cover</strong>
        <Input v-model:value="draft" aria-label="QR token draft" style="width: 112px; max-width: 100%" />
      </template>
    </QrCode>
  </ConfigProvider>
</template>
```

---

# Radio

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/radio


从多个选项中选择一个标量值。使用 `RadioGroup` / `Radio.Group` 管理一组选项；按钮外观使用 `RadioButton` / `Radio.Button` 或 Group 的 `optionType="button"`。

## API

### Radio / RadioButton

| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| checked / defaultChecked | 受控选中值 / 非受控初值；支持 `v-model:checked` | `boolean` | — / `false` |
| value | Group 内的标量身份；组外为原生 input 的 value | `string \| number \| boolean` | — |
| disabled | 本项优先，再取 Group 与 ConfigProvider 的禁用配置；显式 false 生效 | `boolean` | — |
| title | 原生 label 的提示 | `string` | — |
| id / name / tabIndex / required / autoFocus | 落到 input；组内 name 由 Group 提供，autoFocus 在挂载时聚焦 | 原生属性 | — |
| prefixCls | DOM 前缀；自定义前缀需配套静态 CSS | `string` | `apollo-radio` |
| classNames / styles | root（label）、icon、label 三个语义区域，支持对象或 `({ props }) => 对象`；props.checked 是当前接受值 | 语义对象或函数 | — |

`Radio` 的 input 类型固定为 radio。无实际职责的 `skipGroup`、`type` 和单项 `optionType` 不再声明；Group 的 `optionType` 保留。

### RadioGroup

| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value / defaultValue | 受控值 / 非受控初值；支持 `v-model:value` | `RadioValue`（string / number / boolean） | — |
| options | 数据选项；非空时优先于 default 槽 | `(string \| number \| RadioOptionItem)[]` | `[]` |
| disabled | 整组禁用；对象选项的显式 disabled 优先 | `boolean` | — |
| name | 所有子 input 的原生 name；省略时每个 Group 生成独立名称 | `string` | 自动生成 |
| optionType | 圆点 / 按钮外观；显式 RadioButton 保持按钮外观 | `'default' \| 'button'` | `'default'` |
| buttonStyle | 按钮填充方式 | `'outline' \| 'solid'` | `'outline'` |
| size | 共享 SizeType；medium / middle 同属默认档 | `'small' \| 'medium' \| 'middle' \| 'large'` | 当前 Provider 尺寸 |
| orientation / vertical | 水平 / 垂直排列；orientation 优先于 vertical | `'horizontal' \| 'vertical'` / boolean | 水平 |
| block | 撑满容器宽度 | `boolean` | `false` |
| id / role / prefixCls | 根 id、角色与前缀 | `string` | — / `radiogroup` / `apollo-radio` |

`RadioOptionItem` 的 value 使用 RadioValue；label 支持完整 Vue 内容。选项保留 style、className、disabled、title、id、required 数据字段；`onChange(event, checked)` 是原生 Radio 通知。数字 1、字符串 '1' 和布尔 false 保持各自身份。

### Emits

| 组件 | 事件 | 载荷 |
|---|---|---|
| Radio / Button | update:checked | `(checked: boolean)` |
| Radio / Button | change | `(event: Event, checked: boolean)`；第二参是本次提议的快照 |
| Radio / Button | click / mouseenter / mouseleave | 原生 MouseEvent；hover 落 label，click 只通知一次 |
| Radio / Button | focus / blur | input 原生 FocusEvent |
| Radio / Button | keydown / keypress | input 原生 KeyboardEvent |
| Group | update:value | `(value: RadioValue)` |
| Group | change | `(value: RadioValue, event: Event)`；只有值发生变化才提议 |
| Group | mouseenter / mouseleave | 根原生 MouseEvent |
| Group | focus / blur | 根或后代产生的原生 FocusEvent |

所有通知由 Vue emits 拥有。`RadioChangeEvent` 是 Event 的类型别名，不含合成 target/nativeEvent。Radio 可直接使用 `@change.stop`；Group 的 change 首参是业务值，需要停止原生传播时使用第二参 event。h() 原生监听按 `onKeydown`、`onMouseenter` 拼写，模板使用 `@keydown`、`@mouseenter`。

受控更新是提议；父级拒绝时，DOM 恢复当前接受值（同名 Group 同时恢复被浏览器取消的兄弟项），随后撤控仍保留最后接受值。input、wrapper 和语义 props.checked 使用同一状态。

### Slots、attrs 与 ref

Radio / Button 的 default 槽支持文本、0、数组、Fragment 和 Vue 节点，空值、布尔值及注释占位不产生空文案层。Group 的 default 槽放自定义 Radio / Button；非空 options 优先。

Radio / Button 的 class、style 落外层 label，其余原生 attrs 落 input；title 落 label。style 支持 Vue 字符串、对象和数组。Group 的原生 attrs、class、style 和监听落 div，声明的业务 props 不落 DOM。原生 capture 监听与所属通知同时保留。

| 引用 | 暴露 |
|---|---|
| Radio / Button | `focus(options?)`、`blur()`、`input: HTMLInputElement \| null`、`nativeElement: HTMLElement \| null`（icon span） |
| Group | `nativeElement: HTMLDivElement \| null` |

引用由真实 Vue 模板 ref 提供；元素在挂载前和卸载后为空。Button 直接转发实际 Radio 引用和通知。

原生 Tab / Space / 方向键负责导航与选择，禁用项跳过；keydown 的 preventDefault() 保留原生取消能力。当前已聚焦的选项在 keyed options 重排后保留焦点，移除项不会把焦点抢回。独立选项集合使用不同 Group，自动生成的 name 互不影响。

## Provider 与 Token

`ConfigProvider.components.radio` 的 className/style/classNames/styles 读取当前配置；本地语义样式和原生根 style 按顺序覆盖。方向、禁用、尺寸及配置替换/撤回均响应变化。

`theme.token`、当前算法与 `theme.components.Radio` 在实际 Group 和 Radio/Button 根投影为静态 CSS 消费的变量。现有 16 个 Token 均生效；radioSize / dotSize 为无单位数字，另两个数值间距转换为 px。wireframe 使用当前主题派生 dotSize、radioColor、radioBgColor；撤回后恢复默认值。

| Token | 说明 | 默认值 |
|---|---|---|
| radioSize | 单选框尺寸 | `16`（unitless） |
| dotSize | 内点尺寸 | `6`（unitless） |
| dotColorDisabled | 禁用内点颜色 | `colorTextDisabled` |
| buttonSolidCheckedColor | solid 按钮选中文字色 | `colorTextLightSolid` |
| buttonSolidCheckedBg | solid 按钮选中背景 | `colorPrimary` |
| buttonSolidCheckedHoverBg | solid 按钮选中 hover 背景 | `colorPrimaryHover` |
| buttonSolidCheckedActiveBg | solid 按钮选中 active 背景 | `colorPrimaryActive` |
| buttonBg | 按钮背景 | `colorBgContainer` |
| buttonCheckedBg | 按钮选中背景 | `colorBgContainer` |
| buttonColor | 按钮文字色 | `colorText` |
| buttonCheckedBgDisabled | 按钮选中禁用背景 | `controlItemBgActiveDisabled` |
| buttonCheckedColorDisabled | 按钮选中禁用文字色 | `colorTextDisabled` |
| buttonPaddingInline | 按钮水平内边距 | `padding - lineWidth` |
| wrapperMarginInlineEnd | wrapper 的 inline-end 外边距 | `marginXS` |
| radioColor | 内点颜色（wireframe 分支） | `colorWhite` |
| radioBgColor | 选中背景（wireframe 分支） | `colorPrimary` |


默认 CSS 保留变量 fallback。手工使用原生根 style 覆盖 `--apollo-radio-*` 时优先级最高；自定义 prefixCls 只改变 DOM 和相应组件变量名，不在运行时生成 CSS 选择器。


## 基本用法 (basic)

最简单的用法：单独使用时受控 / 非受控均可。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { Radio } from '@apollo-design/ui';
</script>

<template>
  <Radio>Radio</Radio>
</template>
```

## 不可用 (disabled)

Radio 不可用：`disabled` 可作用于单个 Radio，也可整组生效。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 disabled demo
import { Button, Radio } from '@apollo-design/ui';
import { ref } from 'vue';

const disabled = ref(true);
</script>

<template>
  <Radio :default-checked="false" :disabled="disabled">Disabled</Radio>
  <Radio default-checked :disabled="disabled">Disabled</Radio>
  <br />
  <!-- ⚠️ 内联 style 的数字必须写 px 字符串（Vue 的 patchStyle 不做数字→px 转换） -->
  <Button type="primary" :style="{ marginTop: '16px' }" @click="disabled = !disabled">
    Toggle disabled
  </Button>
</template>
```

## 单选组合 (radiogroup)

一组互斥的单选项。`options` 的 `label` 可以是任意节点，常用来放图标 + 文字。

### radiogroup.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 radiogroup demo（图标 + 垂直排列的标签内容）
import {
  BarChartOutlined,
  DotChartOutlined,
  LineChartOutlined,
  PieChartOutlined,
} from '@apollo-design/icons';
import { Flex, Radio } from '@apollo-design/ui';
import { type Component, h, ref } from 'vue';

const value = ref(1);

/** 与 antd 的 `label: <Flex vertical gap="small" justify="center" align="center">…</Flex>` 同构。 */
const chartLabel = (Icon: Component, text: string) =>
  h(
    Flex,
    { gap: 'small', justify: 'center', align: 'center', vertical: true },
    { default: () => [h(Icon, { style: { fontSize: '18px' } }), text] },
  );

const options = [
  { value: 1, className: 'option-1', label: chartLabel(LineChartOutlined, 'LineChart') },
  { value: 2, className: 'option-2', label: chartLabel(DotChartOutlined, 'DotChart') },
  { value: 3, className: 'option-3', label: chartLabel(BarChartOutlined, 'BarChart') },
  { value: 4, className: 'option-4', label: chartLabel(PieChartOutlined, 'PieChart') },
];
</script>

<template>
  <Radio.Group v-model:value="value" :options="options" />
</template>
```

## 单选组合 - 配合 options (radiogroup-options)

`options` 支持字符串 / 数字 / 对象三种元素形态；配合 `optionType="button"` 与
`buttonStyle="solid"` 可切换为按钮形态。

### radiogroup-options.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 radiogroup-options demo（options 的四种写法 × 两种形态）
import { Radio } from '@apollo-design/ui';
import { ref } from 'vue';

const plainOptions = ['Apple', 'Pear', 'Orange'];

const options = [
  { label: 'Apple', value: 'Apple', className: 'label-1' },
  { label: 'Pear', value: 'Pear', className: 'label-2' },
  { label: 'Orange', value: 'Orange', title: 'Orange', className: 'label-3' },
];

const optionsWithDisabled = [
  { label: 'Apple', value: 'Apple', className: 'label-1' },
  { label: 'Pear', value: 'Pear', className: 'label-2' },
  { label: 'Orange', value: 'Orange', className: 'label-3', disabled: true },
];

const value1 = ref('Apple');
const value2 = ref('Apple');
const value3 = ref('Apple');
const value4 = ref('Apple');
</script>

<template>
  <Radio.Group v-model:value="value1" :options="plainOptions" />
  <br />
  <Radio.Group v-model:value="value2" :options="optionsWithDisabled" />
  <br />
  <br />
  <Radio.Group v-model:value="value3" :options="options" option-type="button" />
  <br />
  <br />
  <Radio.Group
    v-model:value="value4"
    :options="optionsWithDisabled"
    option-type="button"
    button-style="solid"
  />
</template>
```

## 单选组合 - 更多用法 (radiogroup-more)

垂直的 `Radio.Group`，配合更多输入项。

### radiogroup-more.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 radiogroup-more demo（垂直组合 + 额外输入项）
import { Flex, Input, Radio } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref(1);

/** antd 的 `labelStyle`（高 32 / 行高 32px）—— 内联样式走 px 字符串。 */
const labelStyle = { height: '32px', lineHeight: '32px' };

const buttonOptions = [
  { label: 'Apple', value: 'Apple', className: 'label-1' },
  { label: 'Pear', value: 'Pear', className: 'label-2' },
  { label: 'Orange', value: 'Orange', title: 'Orange', className: 'label-3' },
];
</script>

<template>
  <Flex align="start" gap="large" wrap>
    <div :style="{ flex: 1 }">
      <Radio.Group v-model:value="value" vertical>
        <Radio :value="1" :style="labelStyle">Option A</Radio>
        <Radio :value="2" :style="labelStyle">Option B</Radio>
        <Radio :value="3" :style="labelStyle">Option C</Radio>
        <Radio :value="4" :style="labelStyle">
          More...
          <Input v-if="value === 4" variant="filled" class="demo-radio-filled-input" aria-label="更多选项内容" placeholder="please input" />
        </Radio>
      </Radio.Group>
    </div>
    <div :style="{ flex: 1 }">
      <Radio.Group :options="buttonOptions" option-type="button" vertical />
    </div>
  </Flex>
</template>

<style>
.demo-radio-filled-input {
  width: 120px;
  margin-inline-start: 12px;

}
</style>
```

## 单选组合 - 带 name (radiogroup-with-name)

传入 `name` 让整组的原生 `input` 共用一个 name（原生 radio 分组语义）。
不传时组件会自己生成一个整组一致的 name。

### radiogroup-with-name.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 radiogroup-with-name demo
import { Radio } from '@apollo-design/ui';

const options = [
  { value: 1, label: 'A' },
  { value: 2, label: 'B' },
  { value: 3, label: 'C' },
  { value: 4, label: 'D' },
];
</script>

<template>
  <Radio.Group name="radiogroup" :default-value="1" :options="options" />
</template>
```

## 单选组合 - block (radiogroup-block)

`block` 属性使 `Radio.Group` 撑满父容器宽度。

### radiogroup-block.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 radiogroup-block demo
import { Flex, Radio } from '@apollo-design/ui';

const options = [
  { label: 'Apple', value: 'Apple' },
  { label: 'Pear', value: 'Pear' },
  { label: 'Orange', value: 'Orange' },
];
</script>

<template>
  <Flex vertical gap="medium">
    <Radio.Group block :options="options" default-value="Apple" />
    <Radio.Group block :options="options" default-value="Apple" option-type="button" button-style="solid" />
    <Radio.Group block :options="options" default-value="Pear" option-type="button" />
  </Flex>
</template>
```

## 按钮样式 (radiobutton)

按钮样式的单选组合（`Radio.Button`）。

### radiobutton.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 radiobutton demo（按钮形态的三态：正常 / 单项禁用 / 整组禁用）
import { Flex, Radio } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="medium">
    <Radio.Group default-value="a">
      <Radio.Button value="a">Hangzhou</Radio.Button>
      <Radio.Button value="b">Shanghai</Radio.Button>
      <Radio.Button value="c">Beijing</Radio.Button>
      <Radio.Button value="d">Chengdu</Radio.Button>
    </Radio.Group>
    <Radio.Group default-value="a">
      <Radio.Button value="a">Hangzhou</Radio.Button>
      <Radio.Button value="b" disabled>Shanghai</Radio.Button>
      <Radio.Button value="c">Beijing</Radio.Button>
      <Radio.Button value="d">Chengdu</Radio.Button>
    </Radio.Group>
    <Radio.Group disabled default-value="a">
      <Radio.Button value="a">Hangzhou</Radio.Button>
      <Radio.Button value="b">Shanghai</Radio.Button>
      <Radio.Button value="c">Beijing</Radio.Button>
      <Radio.Button value="d">Chengdu</Radio.Button>
    </Radio.Group>
  </Flex>
</template>
```

## 填底按钮样式 (radiobutton-solid)

实色填底的单选按钮样式（`buttonStyle="solid"`）。

### radiobutton-solid.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 radiobutton-solid demo
import { Flex, Radio } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="medium">
    <Radio.Group default-value="a" button-style="solid">
      <Radio.Button value="a">Hangzhou</Radio.Button>
      <Radio.Button value="b">Shanghai</Radio.Button>
      <Radio.Button value="c">Beijing</Radio.Button>
      <Radio.Button value="d">Chengdu</Radio.Button>
    </Radio.Group>
    <Radio.Group default-value="c" button-style="solid">
      <Radio.Button value="a">Hangzhou</Radio.Button>
      <Radio.Button value="b" disabled>Shanghai</Radio.Button>
      <Radio.Button value="c">Beijing</Radio.Button>
      <Radio.Button value="d">Chengdu</Radio.Button>
    </Radio.Group>
  </Flex>
</template>
```

## 尺寸 (size)

`size` 只对按钮形态（`optionType="button"`）生效：`large` / 默认 / `small`。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size demo（按钮形态的三档尺寸）
import { Flex, Radio } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="medium">
    <Radio.Group default-value="a" size="large">
      <Radio.Button value="a">Hangzhou</Radio.Button>
      <Radio.Button value="b">Shanghai</Radio.Button>
      <Radio.Button value="c">Beijing</Radio.Button>
      <Radio.Button value="d">Chengdu</Radio.Button>
    </Radio.Group>
    <Radio.Group default-value="a">
      <Radio.Button value="a">Hangzhou</Radio.Button>
      <Radio.Button value="b">Shanghai</Radio.Button>
      <Radio.Button value="c">Beijing</Radio.Button>
      <Radio.Button value="d">Chengdu</Radio.Button>
    </Radio.Group>
    <Radio.Group default-value="a" size="small">
      <Radio.Button value="a">Hangzhou</Radio.Button>
      <Radio.Button value="b">Shanghai</Radio.Button>
      <Radio.Button value="c">Beijing</Radio.Button>
      <Radio.Button value="d">Chengdu</Radio.Button>
    </Radio.Group>
  </Flex>
</template>
```

## 语义化样式 (style-class)

通过 `classNames` / `styles` 自定义三槽（root / icon / label）；两者都支持对象与
函数两种形态，函数形态能拿到 `checked` 等合并后的 props。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo（语义化三槽：root / icon / label）
// ⚠️ PLATFORM 替换：antd 用 antd-style 的 createStyles 生成类名；本仓零运行时，
//    类名与样式都由 demo 自己的 <style> 提供（两边机制本就不同，比的是挂载结果）。
import { Flex, Radio } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<'styles' | 'classNames'>('styles');

/** 对象形态的 `styles`。 */
const styles = {
  icon: { borderRadius: '6px' },
  label: { color: 'var(--apollo-color-primary-text)' },
};

/** 函数形态的 `classNames` —— 按选中态动态返回（antd 同 demo 的写法）。 */
const classNamesFn = (info: { props: { checked?: boolean } }) =>
  info.props.checked
    ? {
        root: 'demo-radio-style-root demo-radio-style-root-checked',
        icon: 'demo-radio-style-icon demo-radio-style-icon-checked',
        label: 'demo-radio-style-label demo-radio-style-label-checked',
      }
    : {
        root: 'demo-radio-style-root',
        icon: 'demo-radio-style-icon',
        label: 'demo-radio-style-label',
      };
</script>

<template>
  <Flex vertical gap="medium">
    <Radio
      name="style-class"
      :styles="styles"
      :checked="value === 'styles'"
      @change="value = 'styles'"
    >
      Object styles
    </Radio>
    <Radio
      name="style-class"
      :class-names="classNamesFn"
      :checked="value === 'classNames'"
      @change="value = 'classNames'"
    >
      Function classNames
    </Radio>
  </Flex>
</template>

<style>
.demo-radio-style-root {
  border-radius: 6px;
  background-color: var(--apollo-color-bg-container);
}
.demo-radio-style-icon {
  border-color: #faad14;
}
.demo-radio-style-label {
  color: var(--apollo-color-text-secondary);
  font-weight: bold;
}
.demo-radio-style-icon-checked {
  background-color: #faad14;
}
.demo-radio-style-label-checked {
  color: var(--apollo-color-warning-text);
}
</style>
```

## 与 Badge 一起使用 (badge)

Badge 包裹 `Radio.Button` —— 垂直形态下组内的边框合并规则也会跟着切换。

### badge.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 badge demo（Badge 包裹 Radio.Button 的两种方向）
import { Badge, Flex, Radio } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="middle" align="start">
    <Radio.Group button-style="solid">
      <Badge :count="1">
        <Radio.Button :value="1">Click Me</Radio.Button>
      </Badge>
      <Badge :count="2">
        <Radio.Button :value="2">Not Me</Radio.Button>
      </Badge>
    </Radio.Group>
    <Radio.Group vertical button-style="solid">
      <Badge :count="1">
        <Radio.Button value="vertical-1">Click Me</Radio.Button>
      </Badge>
      <Badge :count="0">
        <Radio.Button value="vertical-0">Hidden Badge</Radio.Button>
      </Badge>
      <Badge :count="2">
        <Radio.Button value="vertical-2">Not Me</Radio.Button>
      </Badge>
    </Radio.Group>
  </Flex>
</template>
```

## 组件 Token (component-token)

通过 `ConfigProvider :theme="{ components: { Radio: { ... } } }"` 设置当前子树的组件 Token。
示例覆盖尺寸、按钮配色和间距；数值长度会转换为 px，`radioSize` / `dotSize` 保持无单位。

### component-token.vue

```vue
<script setup lang="ts">
import { ConfigProvider, Radio, Space } from '@apollo-design/ui';

const theme = {
  components: {
    Radio: {
      radioSize: 20,
      dotSize: 10,
      dotColorDisabled: 'var(--apollo-color-text-disabled)',
      buttonBg: 'color-mix(in srgb, #52c41a 8%, var(--apollo-color-bg-container))',
      buttonCheckedBg: 'color-mix(in srgb, #52c41a 24%, var(--apollo-color-bg-container))',
      buttonColor: 'var(--apollo-color-text)',
      buttonPaddingInline: 20,
      buttonCheckedBgDisabled: 'var(--apollo-color-fill-tertiary)',
      buttonCheckedColorDisabled: 'var(--apollo-color-text-disabled)',
      buttonSolidCheckedColor: 'var(--apollo-color-text-light-solid)',
      wrapperMarginInlineEnd: 20,
    },
  },
};
</script>

<template>
  <ConfigProvider :theme="theme">
    <Space orientation="vertical">
      <Radio checked>Test</Radio>
      <Radio checked disabled>Disabled</Radio>
      <Radio.Group default-value="a" aria-label="Cities">
        <Radio.Button value="a">Hangzhou</Radio.Button>
        <Radio.Button value="b">Shanghai</Radio.Button>
        <Radio.Button value="c">Beijing</Radio.Button>
        <Radio.Button value="d">Chengdu</Radio.Button>
      </Radio.Group>
      <Radio.Group default-value="a" disabled aria-label="Disabled cities">
        <Radio.Button value="a">Hangzhou</Radio.Button>
        <Radio.Button value="b">Shanghai</Radio.Button>
        <Radio.Button value="c">Beijing</Radio.Button>
        <Radio.Button value="d">Chengdu</Radio.Button>
      </Radio.Group>
      <Radio.Group default-value="a" button-style="solid" aria-label="Solid cities">
        <Radio.Button value="a">Hangzhou</Radio.Button>
        <Radio.Button value="b">Shanghai</Radio.Button>
        <Radio.Button value="c">Beijing</Radio.Button>
        <Radio.Button value="d">Chengdu</Radio.Button>
      </Radio.Group>
    </Space>
  </ConfigProvider>
</template>
```

## 线框风格 (wireframe)

通过 `ConfigProvider :theme="{ token: { wireframe: true } }"` 切换线框风格。
线框风格下选中点使用主色，点尺寸也更大；撤回配置会恢复当前主题默认值。

### wireframe.vue

```vue
<script setup lang="ts">
import { ConfigProvider, Radio } from '@apollo-design/ui';

const options = [
  { value: 1, label: 'A' },
  { value: 2, label: 'B' },
  { value: 3, label: 'C' },
  { value: 4, label: 'D' },
];
</script>

<template>
  <ConfigProvider :theme="{ token: { wireframe: true } }">
    <Radio.Group :value="1" :options="options" aria-label="Wireframe" />
    <br />
    <Radio.Group :value="1" :options="options" disabled aria-label="Disabled wireframe" />
  </ConfigProvider>
</template>
```

---

# Rate

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/rate


评分组件。

## 何时使用

- 对内容进行快速评级操作。
- 展示评价结果（配合 `disabled` 只读态）。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/rate/demo)（9 个，覆盖 antd 的主要用户场景）。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 当前值（受控，`v-model:value`） | `number` | — |
| defaultValue | 默认值 | `number` | `0` |
| count | 星星总数 | `number` | `5` |
| allowHalf | 允许半星 | `boolean` | `false` |
| allowClear | 再次点击同值清零 | `boolean` | `true` |
| keyboard | 键盘方向键控制 | `boolean` | `true` |
| disabled | 只读（与 DisabledContext 合并） | `boolean` | `false` |
| size | 尺寸 | `'large' \| 'middle' \| 'small'` | `'middle'` |
| tooltips | 每颗星的提示（string 或 TooltipProps 对象） | `(TooltipProps \| string)[]` | — |
| direction | 文本方向（rtl 时半星/方向键反向） | `'ltr' \| 'rtl'` | `'ltr'` |
| autoFocus | 挂载后自动聚焦 | `boolean` | `false` |
| tabIndex | 当前星项焦点入口的 tabIndex；其余星项及根元素为 `-1` | `number` | `0` |
| id | 根 `ul` 的 id | `string` | — |
| prefixCls | 组件类名前缀 | `string` | `apollo-rate` |

### Events

| 事件 | 说明 | 载荷 |
|---|---|---|
| update:value | 评分更新请求，供 `v-model:value` 使用 | `number` |
| change | 评分更新请求，先于 `update:value` 触发 | `number` |
| hoverChange | 当前悬停值；移出时为 `undefined` | `number \| undefined` |
| focus | 焦点进入评分组 | `FocusEvent` |
| blur | 焦点离开评分组；组内移动不重复触发 | `FocusEvent` |

组件事件支持 Vue 的 `.once`。`@keydown`、`@mouseleave` 等原生监听器及 `class` / `style`、`aria-label`、`aria-labelledby`、`data-*` 落在根 `ul`，键盘事件先处理评分再通知监听器。disabled 时抑制键盘处理与通知。已有 `onKeyDown` / `onMouseLeave` 拼写仍走同一原生事件通道。

`value` 为受控值：父级未回传时保持原评分；移除 `value` 后沿用最后一次已接收值。`defaultValue` 只用于非受控初始值。悬停仅改变预览和 `#character.value`，不会改变已选项或模型。

根元素为 `radiogroup`，请提供 `aria-label` 或 `aria-labelledby`。当前星项是唯一的 Tab 入口；评分为 `0` 时进入第一项，半星值由对应的下一整星项表示并读出实际值。左右方向键更新评分并跟随焦点，RTL 时方向反转，Enter/空格选择当前项，`allowClear` 允许再次激活清零。disabled 时全部星项退出 Tab 序列。

### Slots

| 插槽 | 说明 | 参数 |
|---|---|---|
| #character | 自定义星星字符（默认 StarFilled） | `{ index, value, allowHalf, disabled, count, focused }` |
| #characterRender | 包装整颗星节点（tooltips 包装在内层组合生效） | `{ node, index }` |

> ⚠️ C8-R2：antd 的 `character`（ReactNode）与 `characterRender`（fn）在本仓**一律是
> 插槽**，不保留同名 prop。`tooltips` 是数据 prop（string / TooltipProps 对象），保留。

### Expose

| 方法 | 说明 |
|---|---|
| focus() | 聚焦当前星项（disabled 时无效） |
| blur() | 移除评分组内的实际焦点（disabled 时无效） |

### 开发期迁移

`change`、`hoverChange`、`focus`、`blur` 已声明为 Vue emits，原有 `@change` / `onChange` 等监听写法继续工作。`focus` / `blur` 现在提供原生 `FocusEvent`；焦点与 `tabIndex` 的目标由根容器调整为当前 radio 项。`#character.value` 与视觉预览一致；动态添加或移除 tooltips 保留星项 DOM 和焦点。

### Component Token

通过 `ConfigProvider` 的 `theme.components.Rate` 覆盖当前评分组件的六个 Token。嵌套 Provider 按字段继承，替换或移除覆盖后恢复当前全局主题的派生值；自定义 `prefixCls` 使用对应的组件变量名。

| Token | 说明 | 默认值 |
|---|---|---|
| starColor | 已选星颜色 | `yellow6` |
| starBg | 未选星颜色 | `colorFillContent` |
| starSize | 标准星尺寸 | `controlHeight × 0.625` |
| starSizeSM | 小星尺寸 | `controlHeightSM × 0.625` |
| starSizeLG | 大星尺寸 | `controlHeightLG × 0.625` |
| starHoverScale | 悬停和键盘焦点缩放 | `scale(1.1)` |

尺寸数字按像素处理，也可通过主题配置提供 CSS 长度字符串。样式优先级为主题 Token、`components.rate.style`、组件原生 `style`；无活动源码主题时沿用静态 CSS 变量。

## 设计说明

- **rc-rate 1.0.1 内核的 Vue 自建**（Rate + Star + util.getOffsetLeft 逐字移植）。
- **cleanedValue**：allowClear 重置后记录被清的值，hover 判据 `nextHoverValue !== cleanedValue`
  防止清零后 hover 回同一值闪烁。
- **tooltips × characterRender 组合**：antd 里用户 characterRender 会覆盖 tooltip 包装
  （JSX spread 在后）；本仓为 slot 组合（先 Tooltip 再用户插槽）。
- hover 时整条星星按 `hoverValue ?? value` 重算类名（rc 语义）。


## basic (basic)

聚焦评分后用左右方向键更新分数。`@keydown` 注册原生键盘监听器，每次按键调用一次，和 `v-model:value` 同时工作；禁用时不处理评分键盘事件。

### basic.vue

```vue
<script setup lang="ts">
import { Rate } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref(0);
const keys = ref(0);
</script>

<template>
  <div>
    <Rate v-model:value="value" aria-label="Rating" @keydown="keys++" />
    <output>{{ value }} · Keyboard events: {{ keys }}</output>
  </div>
</template>
```

## character (character)

`#character` 插槽自定义星星字符（可传 VNode 或文本）。

### character.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/character.tsx（C8-R2：character ReactNode → #character 插槽）
import { HeartOutlined } from '@apollo-design/icons';
import { Flex, Rate } from '@apollo-design/ui';
import { h } from 'vue';
</script>

<template>
  <Flex vertical gap="medium">
    <Rate allow-half #character>
      <HeartOutlined />
    </Rate>
    <Rate allow-half style="font-size: 36px" #character>A</Rate>
    <Rate allow-half #character>好</Rate>
  </Flex>
</template>
```

## character-function (character-function)

`#character` 作用域插槽按星序自定义渲染（antd `character({ index })` 函数形态的对应物）。

### character-function.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/character-function.tsx（character fn → #character 作用域插槽）
import { FrownOutlined, MehOutlined, SmileOutlined } from '@apollo-design/icons';
import { Flex, Rate } from '@apollo-design/ui';
import { h, type VNodeChild } from 'vue';

const customIcons: Record<number, VNodeChild> = {
  1: h(FrownOutlined),
  2: h(FrownOutlined),
  3: h(MehOutlined),
  4: h(SmileOutlined),
  5: h(SmileOutlined),
};
</script>

<template>
  <Flex vertical gap="medium">
    <Rate :default-value="2" #character="{ index }">
      {{ index + 1 }}
    </Rate>
    <Rate :default-value="3" #character="{ index }">
      <component :is="customIcons[index + 1]" />
    </Rate>
  </Flex>
</template>
```

## clear (clear)

再次点击同值可以清零（`allowClear` 默认为 true）。

### clear.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/clear.tsx
import { Flex, Rate } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="medium">
    <Flex gap="medium" wrap align="center">
      <Rate :default-value="3" />
      <span>allowClear: true</span>
    </Flex>
    <Flex gap="medium" wrap align="center">
      <Rate :default-value="3" :allow-clear="false" />
      <span>allowClear: false</span>
    </Flex>
  </Flex>
</template>
```

## component-token (component-token)

通过 ConfigProvider 的 `theme.components.Rate` 覆盖六个组件 Token，包括三档尺寸、选中与未选中颜色和悬停缩放。

### component-token.vue

```vue
<script setup lang="ts">
import { ConfigProvider, Flex, Rate } from '@apollo-design/ui';
</script>

<template>
  <ConfigProvider
    :theme="{
      components: {
        Rate: {
          starColor: '#1677ff',
          starBg: '#d9d9d9',
          starSize: 32,
          starSizeSM: 24,
          starSizeLG: 40,
          starHoverScale: 'scale(1.2)',
        },
      },
    }"
  >
    <Flex vertical gap="small">
      <Rate :default-value="2.5" allow-half aria-label="Standard token rating" />
      <Rate size="small" :default-value="2.5" allow-half aria-label="Small token rating" />
      <Rate size="large" :default-value="2.5" allow-half aria-label="Large token rating" />
    </Flex>
  </ConfigProvider>
</template>
```

## disabled (disabled)

只读，无法进行交互（`role="radio"` 全部 `aria-checked` 只反映当前值）。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/disabled.tsx
import { Rate } from '@apollo-design/ui';
</script>

<template>
  <Rate disabled :default-value="2" />
</template>
```

## half (half)

支持选中半星（`allowHalf`）。

### half.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/half.tsx
import { Rate } from '@apollo-design/ui';
</script>

<template>
  <Rate allow-half :default-value="2.5" />
</template>
```

## size (size)

`size="large"` / `size="small"` 两档尺寸。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/size.tsx
import { Flex, Rate } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="medium">
    <Rate size="large" />
    <Rate />
    <Rate size="small" />
  </Flex>
</template>
```

## text (text)

`tooltips` 数据 prop 为每颗星加提示（string 或 TooltipProps 对象）；`v-model:value` 受控。

### text.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/text.tsx（tooltips 数据 prop；TooltipProps 对象形态逐字支持）

import type { TooltipProps } from '@apollo-design/ui';
import { Flex, Rate } from '@apollo-design/ui';
import { ref } from 'vue';

const desc: (TooltipProps | string)[] = [
  'terrible',
  { placement: 'top', title: 'bad', trigger: 'hover' },
  'normal',
  'good',
  'wonderful',
];
const value = ref(3);

const getDescTitle = (v: number) => {
  const item = desc[v - 1];
  return item && typeof item === 'object' ? item.title : item;
};
</script>

<template>
  <Flex vertical gap="medium">
    <Rate v-model:value="value" :tooltips="desc" @change="(v: number) => (value = v)" />
    <span v-if="value">{{ getDescTitle(value) }}</span>
  </Flex>
</template>
```

---

# Result

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/result


展示操作结果、异常说明及后续操作。标题内容需要业务语义时，可通过 `#title` 放置合适级别的标题。

## 何时使用

用于结果反馈较复杂、需要标题、说明、正文或操作区的页面。

## 代码演示

十个实际示例包括四种普通状态、403/404/500静态插画、完整自定义图标、六个语义落点和可开关组件主题。

## API

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| status | 普通状态或异常代码；数字和字符串异常代码等价 | `'success' \| 'error' \| 'info' \| 'warning' \| 403 \| 404 \| 500 \| '403' \| '404' \| '500'` | `'info'` |
| icon | 默认图形开关，`false`/`null`隐藏，`true`/未传显示；存在`#icon`时插槽优先 | `boolean \| null` | — |
| title | 标题文本；存在`#title`时插槽优先 | `string` | — |
| subTitle | 副标题文本；存在`#subTitle`时插槽优先 | `string` | — |
| prefixCls | 当前类名前缀；任意前缀的静态CSS须由应用提供 | `string` | Provider前缀 |
| classNames | 六个语义落点的类或读取当前Props的工厂 | `ResultSemanticClassNames \| ((info: { props: ResultProps }) => ResultSemanticClassNames)` | — |
| styles | 六个语义落点的样式或读取当前Props的工厂 | `ResultSemanticStyles \| ((info: { props: ResultProps }) => ResultSemanticStyles)` | — |

### Slots

| 插槽 | 内容 |
|---|---|
| icon | 完整自定义图标内容，所有状态均覆盖默认图形；可含原生交互内容 |
| title / subTitle | 完整标题/副标题内容，优先于同名文本prop |
| extra | 操作区 |
| default | 正文 |

五个插槽均无参数，支持多节点、Fragment、注释与原生控件。存在但为空的插槽不回退默认内容，也不留下空容器；移除插槽才恢复默认。`0`为有效文本。状态/主题变化保留仍存在的业务节点；被条件移除的内容按Vue正常卸载。

### 原生属性、事件和实例

`class`、字符串/数组/对象`style`、id、aria/data、tabindex和原生监听作用于根div。类拼接，语义样式覆盖Provider配置，根原生style最后生效。没有业务Emits或v-model；例如`@click`接收根原生事件，触发一次。

`ResultRef.nativeElement: HTMLElement | null`指向根节点，卸载后为null。组件不自动聚焦、不声明alert/live区域；需要时由调用者提供原生role/aria属性。

### Provider、语义和主题

`components.result`支持当前`className/style/classNames/styles`，替换、删除和恢复均生效。`className/style`在配置对象中是有效根配置，不是组件根属性别名。最近Provider、direction与prefix响应更新。六个语义名称为`root/title/subTitle/body/extra/icon`。

四个组件Token通过`theme.components.Result`配置，也可由根CSS变量覆盖。源主题Alias、普通/暗色/紧凑及组合算法即时更新；局部配置不影响相邻实例。

| Token | 类型 | 默认值 | CSS变量 |
|---|---|---|---|
| titleFontSize | `number \| string` | `fontSizeHeading3` | `--apollo-result-title-font-size` |
| subtitleFontSize | `number \| string` | `fontSize` | `--apollo-result-subtitle-font-size` |
| iconFontSize | `number \| string` | `fontSizeHeading3 × 3` | `--apollo-result-icon-font-size` |
| extraMargin | `string` | `paddingLG 0 0 0` | `--apollo-result-extra-margin` |

数字字号按px，0有效；负数和非有限数字回退当前Alias。字符串支持有效CSS长度、变量或calc表达式；空串回退。extraMargin使用CSS margin简写。静态CSS入口为`@apollo-design/ui/style.css`或`@apollo-design/ui/result/style.css`。

### 静态导出与SSR

`PRESENTED_IMAGE_403/404/500`为可重复渲染的静态插画组件，与`ExceptionMap`对应项身份一致；`IconMap`包含四种普通状态。默认异常插画是装饰，普通状态图标保留其图像名称；真实自定义插槽不被隐藏。插画颜色和路径保持静态，直接使用插画组件时可自行提供原生SVG名称。

生产SSR不访问浏览器全局；水合使用相同配置与内容。根入口`@apollo-design/ui`提供具名Result、图标映射与类型；深入口`@apollo-design/ui/result`另提供默认Result导出。本轮开发期行为修正见[集中迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/result-contracts.md)，无旧形态兼容层。


## 成功 (success)

成功的结果。

### success.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 success demo

import { Button, Result, Space } from '@apollo-design/ui';
</script>

<template>
  <Result
    status="success"
    title="Successfully Purchased Cloud Server ECS!"
    sub-title="Order number: 2017182818828182881 Cloud server configuration takes 1-5 minutes, please wait."
  >
    <template #extra>
      <Space wrap :size="8" style="justify-content: center">
        <Button type="primary">Go Console</Button>
        <Button>Buy Again</Button>
      </Space>
    </template>
  </Result>
</template>
```

## 信息提示 (info)

默认 `info` 状态使用信息图标。隐藏默认图形可设置 `:icon="false"`，自定义内容使用 `#icon`。

### info.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 info demo（默认 status = info）。C8-R2：extra 走 `#extra` 插槽。
import { Button, Result } from '@apollo-design/ui';
</script>

<template>
  <Result title="Your operation has been executed">
    <template #extra>
      <Button type="primary">Go Console</Button>
    </template>
  </Result>
</template>
```

## 警告 (warning)

警告的结果。

### warning.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 warning demo。C8-R2：extra 走 `#extra` 插槽。
import { Button, Result } from '@apollo-design/ui';
</script>

<template>
  <Result
    status="warning"
    title="There are some problems with your operation."
    sub-title="More actions please."
  >
    <template #extra>
      <Button type="primary">Go Console</Button>
    </template>
  </Result>
</template>
```

## 403 (403)

无权限页面（静态插画，不随主题变化）。

### 403.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 403 demo（静态插画分支）。C8-R2：extra 走 `#extra` 插槽。
import { Button, Result } from '@apollo-design/ui';
</script>

<template>
  <Result
    status="403"
    title="403"
    sub-title="Sorry, you are not authorized to access this page."
  >
    <template #extra>
      <Button type="primary">Go Console</Button>
    </template>
  </Result>
</template>
```

## 404 (404)

页面不存在。

### 404.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 404 demo。C8-R2：extra 走 `#extra` 插槽。
import { Button, Result } from '@apollo-design/ui';
</script>

<template>
  <Result
    status="404"
    title="404"
    sub-title="Sorry, the page you visited does not exist."
  >
    <template #extra>
      <Button type="primary">Go Console</Button>
    </template>
  </Result>
</template>
```

## 500 (500)

服务器错误。

### 500.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 500 demo。C8-R2：extra 走 `#extra` 插槽。
import { Button, Result } from '@apollo-design/ui';
</script>

<template>
  <Result
    status="500"
    title="500"
    sub-title="Sorry, something went wrong on server."
  >
    <template #extra>
      <Button type="primary">Go Console</Button>
    </template>
  </Result>
</template>
```

## 失败 (error)

复杂错误反馈（含 body 内容区）。

### error.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 error demo（含 body 内容区）。C8-R2：extra 走 `#extra` 插槽。
import { Button, Result, Space } from '@apollo-design/ui';
</script>

<template>
  <Result
    status="error"
    title="Submission Failed"
    sub-title="Please check and modify the following information before resubmitting."
  >
    <template #extra>
      <Space wrap :size="8" style="justify-content: center">
        <Button type="primary">Go Console</Button>
        <Button>Buy Again</Button>
      </Space>
    </template>
    <div class="desc">
      <p style="font-size: 16px">
        <strong>The content you submitted has the following error:</strong>
      </p>
      <p>Your account has been frozen</p>
      <p>Your account is not yet entitled to submit</p>
    </div>
  </Result>
</template>

<style scoped>
.desc p {
  margin-bottom: 4px;
}
</style>
```

## 自定义图标与完整内容 (custom-icon)

普通和异常状态均优先使用完整的 `#icon` 插槽。切换状态保留编辑器，选择有意留空时不回退图标；移除插槽才恢复默认图形。

### custom-icon.vue

```vue
<script setup lang="ts">
import { SmileOutlined } from '@apollo-design/icons';
import { Button, Input, Result, type ResultStatusType, Select } from '@apollo-design/ui';
import { ref } from 'vue';

const status = ref<ResultStatusType>('info');
const mode = ref<'custom' | 'empty' | 'default'>('custom');
const draft = ref('Result draft');
</script>
<template>
  <div style="display:flex;gap:16px;flex-wrap:wrap">
    <label style="display: flex; align-items: center; gap: 8px">结果状态 <Select v-model:value="status" aria-label="Result demo status" style="width: 120px" :options="['info', 'success', 'warning', 'error', '403', '404', '500'].map(value => ({ value, label: value }))" /></label>
    <label style="display: flex; align-items: center; gap: 8px">图标内容 <Select v-model:value="mode" aria-label="Result demo icon" style="width: 140px" :options="[{ value: 'custom', label: '自定义内容' }, { value: 'empty', label: '有意留空' }, { value: 'default', label: '默认图形' }]" /></label>
  </div>
  <Result :status="status" title="Great, we have done all the operations!">
    <template v-if="mode !== 'default'" #icon><template v-if="mode === 'custom'"><!-- Complete native content, including the editor. --><SmileOutlined /><div style="display:flex;justify-content:center;gap:12px;flex-wrap:wrap"><label>备注 <Input v-model:value="draft" aria-label="Result demo draft" style="width:140px" /></label><span>完整图标内容</span></div></template></template>
    <template #extra><Button type="primary">Next</Button></template>
  </Result>
</template>
```

## 自定义语义结构的样式和类 (style-class)

通过 `classNames` / `styles` 自定义语义结构（支持函数式）。

### style-class.vue

```vue
<script setup lang="ts">
import { Button, Result, type ResultProps, type ResultStatusType } from '@apollo-design/ui';
import { ref } from 'vue';

const status = ref<ResultStatusType>('success');
const classNamesObject = {
  root: 'demo-result-root',
  title: 'demo-result-title',
  subTitle: 'demo-result-subtitle',
  icon: 'demo-result-icon',
  extra: 'demo-result-extra',
  body: 'demo-result-body',
};
const styles = ({ props }: { props: ResultProps }) => ({
  root: { borderWidth: '2px', borderStyle: 'dashed', padding: '16px' },
  icon: { opacity: props.status === 'success' ? 0.8 : 1 },
  extra: {
    backgroundColor: 'var(--apollo-color-fill-alter)',
    color: 'var(--apollo-color-text)',
    padding: '8px',
  },
});
</script>
<template>
  <Button aria-label="Toggle Result semantic status" @click="status = status === 'success' ? 'warning' : 'success'">切换结果状态</Button>
  <Result :status="status" title="Successfully Purchased Cloud Server ECS!" sub-title="Order number: 2017182818828182881" :class-names="classNamesObject" :styles="styles">
    <template #extra><Button type="primary">Go Console</Button></template>
    <p>六个语义落点均可配置，样式工厂读取当前结果状态。</p>
  </Result>
</template>
```

## 组件 Token (component-token)

通过当前源主题配置四个 Token，移除与恢复配置保持原生输入。根 `--apollo-result-*` 变量优先于组件主题，移除后恢复当前主题值。

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, Input, Result } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const enabled = ref(true),
  native = ref(false);
const draft = ref('Result token draft');
const theme = computed(() =>
  enabled.value
    ? {
        components: {
          Result: {
            titleFontSize: 32,
            subtitleFontSize: 18,
            iconFontSize: 96,
            extraMargin: '16px 0 0 0',
          },
        },
      }
    : undefined,
);
</script>
<template>
  <div style="display:flex;gap:12px;flex-wrap:wrap">
    <Button aria-label="Toggle Result theme" @click="enabled = !enabled">{{ enabled ? '移除局部主题' : '恢复局部主题' }}</Button>
    <Button aria-label="Toggle Result native font" @click="native = !native">{{ native ? '移除原生字号' : '原生字号优先' }}</Button>
  </div>
  <ConfigProvider :theme="theme">
    <Result class="demo-result-token" status="success" title="操作成功" sub-title="标题、副标题、图标字号与操作区间距均由 Component Token 控制。" :style="native ? { '--apollo-result-title-font-size': '36px' } : undefined">
      <template #extra><Button type="primary">查看详情</Button></template>
      <label>备注 <Input v-model:value="draft" aria-label="Result token draft" /></label><strong>保留原生内容</strong>
    </Result>
  </ConfigProvider>
</template>
```

---

# Segmented

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/segmented


# Segmented 分段控制器

用于展示多个选项并允许用户选择其中单个选项。

## 引入

```ts
import { Segmented } from '@apollo-design/ui';
```

## 代码演示





























## API

通用属性参考：通用属性。

### SegmentedProps

| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| block | 值块占满整行 | boolean | false | |
| disabled | 是否禁用 | boolean | false | |
| options | 数据化配置选项 | `SegmentedOptions` | [] | |
| shape | 形状 | `'default' \| 'round'` | 'default' | |
| size | 控件尺寸 | `'small' \| 'middle' \| 'medium' \| 'large'` | 'middle' | |
| value | 当前值（受控） | SegmentedValue | - | |
| defaultValue | 初始值；未传时选中第一个选项 | SegmentedValue | - | |
| name | 内部 radio input 的 `name` | string | 自动生成 | |
| vertical | 纵向布局（旧 API） | boolean | false | |
| orientation | 布局方向（新 API） | `'horizontal' \| 'vertical'` | - | |
| prefixCls | 类名前缀 | string | - | |
| classNames | 语义化类名（支持函数式） | `{ root, icon, label, item }` | - | |
| styles | 语义化样式（支持函数式） | `{ root, icon, label, item }` | - | |

### 事件

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| update:value | 选中值变化（配合 `v-model:value`） | `(value: SegmentedValue) => void` |
| change | 请求选中值变化 | `(value: SegmentedValue) => void` |
| keydown | 原生键盘事件；先于内部导航，可调用 `preventDefault()` | `(event: KeyboardEvent) => void` |

`change` 与 `update:value` 是 Vue 所属事件；模板使用 `@change` / `v-model:value`，`h()` 使用 `onChange` / `onUpdate:value`，不再手动调用 attrs 中的监听器。

受控时仅提议更新，父级拒绝后恢复原生 radio 的实际勾选；撤控保留最后接受的值。`defaultValue` 只初始化一次，未提供时在首批选项到达后取第一项。后续重排或删除不静默改变选择；受控值不在选项中时保持该值且无项目勾选。

原生 `class`、完整 `style`（对象、字符串、数组）、id、ARIA/data 与监听器落到实际根 div，native style 的优先级高于语义根样式。根本身不增加默认 Tab 停靠点，当前可用 radio（未命中时为首个可用项）是唯一 Tab 入口。方向键跳过禁用项并环绕；水平 RTL 反转左右方向，原生取消和输入法期间不导航。只有父级接受更新才移动键盘焦点。

`ConfigProvider` 的当前禁用、尺寸、方向及 `components.segmented` 语义配置响应更新与撤回，组件 `disabled=false` 可显式覆盖全局禁用。

### SegmentedValue

```ts
type SegmentedValue = string | number;
```

### SegmentedOptions

```ts
type SegmentedOption = SegmentedValue | SegmentedLabeledOption;
type SegmentedOptions = readonly SegmentedOption[];

interface SegmentedLabeledOptionWithoutIcon {
  value: SegmentedValue;
  label: VNodeChild; // 完整 Vue 内容，包括数组和 Fragment
  disabled?: boolean;
  title?: string;
  className?: string;
  id?: string;
  tooltip?: string | TooltipProps;
}

interface SegmentedLabeledOptionWithIcon {
  value: SegmentedValue;
  icon: VNodeChild;
  label?: VNodeChild;
  disabled?: boolean;
  title?: string;
  tooltip?: string | TooltipProps;
}
```

内容通过选项数据提供，`label` / `icon` 接受完整 `VNodeChild`（含 0、数组和 Fragment），不接受未消费的渲染回调。`id` 落到对应 label；原生 radio 的 `value` 是选项值的字符串形式，事件保留原始 string/number 类型。图标选项无文本时以 `title` 或选项值提供原生访问名称，建议填写有意义的 title。

### Ref

```ts
interface SegmentedRef {
  nativeElement: HTMLDivElement | null;
}
```

## 主题变量

| Token | 说明 | 默认值 |
| --- | --- | --- |
| itemColor | 选项文本颜色 | colorTextLabel |
| itemHoverColor | 选项悬浮态文本颜色 | colorText |
| itemHoverBg | 选项悬浮态背景色 | colorFillSecondary |
| itemActiveBg | 选项激活态背景色 | colorFill |
| itemSelectedBg | 选项选中背景色 | colorBgElevated |
| itemSelectedColor | 选项选中文字色 | colorText |
| trackPadding | 控件容器 padding | lineWidthBold |
| trackBg | 控件容器背景色 | colorBgLayout |

`trackPadding` 支持数字（px）或 CSS 长度字符串；其余七项接受 CSS 字符串。通过 `theme.components.Segmented` 覆盖的八项均在实际根生效，并响应替换与移除。


## 基本用法 (basic)

最简单的用法。

窄画布下保留横向选项，可横向滚动；聚焦后用方向键选择，当前选项会滚动到可见区域。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { Segmented } from '@apollo-design/ui';

const handleChange = (value: unknown) => {
  console.log(value);
};
</script>

<template>
  <Segmented
    aria-label="周期"
    style="max-width: 100%; overflow-x: auto"
    :options="['Daily', 'Weekly', 'Monthly', 'Quarterly', 'Yearly']"
    @change="handleChange"
  />
</template>
```

## 受控模式 (controlled)

通过 `v-model:value` 受控。

### controlled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 controlled demo：受控 + v-model:value

import { Segmented } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('Map');
</script>

<template>
  <Segmented v-model:value="value" :options="['Map', 'Transit', 'Satellite']" />
</template>
```

## 占满整行 (block)

`block` 属性使其适配父元素宽度。

### block.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 block demo
import { Segmented } from '@apollo-design/ui';
</script>

<template>
  <Segmented block :options="['Daily', 'Weekly', 'Monthly', 'Quarterly', 'Yearly']" />
</template>
```

## 禁用 (disabled)

`disabled` 支持「整组禁用」与「单项禁用」两种粒度。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 disabled demo
import { Segmented } from '@apollo-design/ui';

const options = [
  { label: 'Daily', value: 'Daily' },
  { label: 'Weekly', value: 'Weekly', disabled: true },
  { label: 'Monthly', value: 'Monthly' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px">
    <Segmented disabled :options="options" />
    <Segmented :options="options" />
  </div>
</template>
```

## 动态选项 (dynamic)

options 动态变化时选中值与 thumb 自动跟随。

窄画布下保留横向选项，可横向滚动；聚焦后用方向键选择，当前选项会滚动到可见区域。

### dynamic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 dynamic demo

import { Button, Segmented } from '@apollo-design/ui';
import { ref } from 'vue';

const options = ref(['Daily', 'Weekly', 'Monthly']);
const moreLoaded = ref(false);

const handleLoadOptions = () => {
  options.value = [...options.value, 'Quarterly', 'Yearly'];
  moreLoaded.value = true;
};
</script>

<template>
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: 8px">
    <Segmented aria-label="周期" style="max-width: 100%; overflow-x: auto" :options="options" />
    <Button type="primary" :disabled="moreLoaded" @click="handleLoadOptions">
      Load more options
    </Button>
  </div>
</template>
```

## 纯图标 (icon-only)

只给 `icon` 不给 `label` 的选项。

### icon-only.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 icon-only demo

import { AppstoreOutlined, BarsOutlined } from '@apollo-design/icons';
import { Segmented } from '@apollo-design/ui';
import { h } from 'vue';

const options = [
  { value: 'List', icon: h(BarsOutlined) },
  { value: 'Kanban', icon: h(AppstoreOutlined) },
];
</script>

<template>
  <Segmented :options="options" />
</template>
```

## 带图标 (with-icon)

`icon` 与 `label` 同时使用；第三方库的裸 `<svg>` 也能对齐（样式层 `-item-icon > svg`）。

### with-icon.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 with-icon demo（含第三方裸 svg 图标对齐判据）

import { AppstoreOutlined, BarsOutlined } from '@apollo-design/icons';
import { Segmented } from '@apollo-design/ui';
import { h } from 'vue';

const CalendarIcon = () =>
  h('svg', {
    viewBox: '0 0 24 24',
    width: '1em',
    height: '1em',
    fill: 'none',
    stroke: 'currentColor',
    'stroke-width': 2,
    'aria-hidden': 'true',
    innerHTML: '<rect x="3" y="4" width="18" height="18" rx="2"/><path d="M16 2v4M8 2v4M3 10h18"/>',
  });

const options = [
  { label: 'List', value: 'List', icon: h(BarsOutlined) },
  { label: 'Kanban', value: 'Kanban', icon: h(AppstoreOutlined) },
  { label: 'Calendar', value: 'Calendar', icon: h(CalendarIcon) },
];
</script>

<template>
  <Segmented :options="options" />
</template>
```

## 自定义渲染 + tooltip (custom)

自定义渲染选项内容，并支持为选项配置 tooltip 提示（`tooltip` 支持 `string | TooltipProps`）。

### custom.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 custom demo。
// ⚠️ demo 替换登记：antd 用 Avatar（P5 未落地）—— 按仓库约定用等价原生结构替换。
import { Segmented, type SegmentedOptions } from '@apollo-design/ui';
import { h } from 'vue';

const users = [
  { label: 'User 1', value: 'user1', tooltip: { title: 'hello user1', color: 'gold' } },
  { label: 'User 2', value: 'user2', tooltip: { title: 'hello user2', color: 'pink' } },
  { label: 'User 3', value: 'user3', tooltip: { title: 'hello user3', color: 'geekblue' } },
];

const seasons: SegmentedOptions = [
  { label: 'Spring', value: 'spring' },
  { label: 'Summer', value: 'summer' },
  { label: [h('b', 'Autumn'), ' 🍂'], value: 'autumn' },
  { label: 'Winter', value: 'winter' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: 8px">
    <Segmented :options="users" />
    <Segmented :options="seasons" />
  </div>
</template>
```

## 圆形 (shape)

`shape="round"` 时根与选项全圆角。

### shape.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 shape demo
import { Segmented } from '@apollo-design/ui';
</script>

<template>
  <Segmented shape="round" :options="['Daily', 'Weekly', 'Monthly']" />
</template>
```

## 三种大小 (size)

`small` / `middle`（默认）/ `large`。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size demo
import { Segmented } from '@apollo-design/ui';
</script>

<template>
  <!-- 🚨 flex 列容器的 align-items 默认 stretch，会把 inline-block 子项拉满宽 -->
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: 8px">
    <Segmented size="large" :options="['Daily', 'Weekly', 'Monthly']" />
    <Segmented :options="['Daily', 'Weekly', 'Monthly']" />
    <Segmented size="small" :options="['Daily', 'Weekly', 'Monthly']" />
  </div>
</template>
```

## 纵向布局 (vertical)

`vertical` 时 thumb 沿纵轴移动。

### vertical.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 vertical demo
import { Segmented } from '@apollo-design/ui';
</script>

<template>
  <Segmented vertical :options="['Daily', 'Weekly', 'Monthly']" />
</template>
```

## 指定 name (with-name)

内部 radio input 的 `name`；未传时自动生成。

### with-name.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 with-name demo
import { Segmented } from '@apollo-design/ui';
</script>

<template>
  <Segmented name="group" :options="['Daily', 'Weekly', 'Monthly']" />
</template>
```

## 语义化 styles (style-class)

`classNames` / `styles` 支持对象与函数式。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo（含函数式 styles）

import { CloudOutlined, RocketOutlined, ThunderboltOutlined } from '@apollo-design/icons';
import { Segmented, type SegmentedProps } from '@apollo-design/ui';
import { h } from 'vue';

const classNames = { root: 'seg-demo-root' };

const styleFn: NonNullable<SegmentedProps['styles']> = (info) => {
  if (info.props.vertical) {
    return {
      root: { border: '1px solid #77BEF0', padding: '4px', width: '100px' },
      icon: { color: '#77BEF0' },
      item: { textAlign: 'start' },
    };
  }
  return {};
};

const styles = { root: { padding: '4px', width: '260px' } };

const options = [
  { label: 'Boost', value: 'boost', icon: h(RocketOutlined) },
  { label: 'Stream', value: 'stream', icon: h(ThunderboltOutlined) },
  { label: 'Cloud', value: 'cloud', icon: h(CloudOutlined) },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Segmented :options="options" :class-names="classNames" :styles="styles" />
    <Segmented :options="options" :class-names="classNames" :styles="styleFn" vertical />
  </div>
</template>
```

## 组件级 Token (component-token)

通过 ConfigProvider 的 `theme.components.Segmented` 覆盖。

窄画布下保留横向选项，可横向滚动；聚焦后用方向键选择，当前选项会滚动到可见区域。

### component-token.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 componentToken demo
import { ConfigProvider, Segmented } from '@apollo-design/ui';
</script>

<template>
  <ConfigProvider
    :theme="{
      components: {
        Segmented: {
          itemColor: 'var(--apollo-color-text)',
          itemHoverColor: 'var(--apollo-color-text)',
          itemHoverBg: 'var(--apollo-color-fill-secondary)',
          itemSelectedBg: 'linear-gradient(225deg, #722ed1 0%, #0958d9 100%)',
          itemActiveBg: 'var(--apollo-color-fill)',
          itemSelectedColor: '#fff',
        },
      },
    }"
  >
    <Segmented aria-label="周期" style="max-width: 100%; overflow-x: auto" :options="['Daily', 'Weekly', 'Monthly', 'Quarterly', 'Yearly']" />
  </ConfigProvider>
</template>
```

## 受控同步 (controlled-two)

两个 `Segmented` 共享同一个受控值：选择任意一个，另一个会同步更新。

### controlled-two.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 controlled-two demo：两个受控 Segmented 共享同一份状态。
import { Segmented, type SegmentedValue } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<SegmentedValue>('AND');
const options = ['AND', 'OR', 'NOT'];
</script>

<template>
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: 12px">
    <Segmented :options="options" :value="value" @update:value="value = $event" />
    <Segmented :options="options" :value="value" @update:value="value = $event" />
    <div>当前值：{{ value }}</div>
  </div>
</template>
```

## 统一高度 (size-consistent)

`Segmented` 与同尺寸的 `Button` 并排时高度保持一致，可用于表单工具栏等需要对齐的场景。

### size-consistent.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size-consistent demo：Segmented 与同尺寸 Button 高度一致。
import { Button, Segmented } from '@apollo-design/ui';

const options = ['Daily', 'Weekly', 'Monthly'];
</script>

<template>
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: 12px">
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 12px">
      <Segmented size="large" :options="options" />
      <Button size="large">Large Button</Button>
    </div>
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 12px">
      <Segmented size="middle" :options="options" />
      <Button size="middle">Middle Button</Button>
    </div>
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 12px">
      <Segmented size="small" :options="options" />
      <Button size="small">Small Button</Button>
    </div>
  </div>
</template>
```

---

# Select

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/select


下拉选择器。

## 何时使用

- 从一组互斥选项中选一个（单选），或一组可叠加的选项中选多个（多选 / 标签）。
- 选项多于 7 个、或需要搜索过滤时，用 Select 代替 Radio。
- 选项总数大（千级以上）时默认走虚拟滚动。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/select/demo)（原生 Vue 示例，含三模型、条件选项、筛选与键盘交互）。

## 条件选项

默认插槽中的 `SelectOption` / `SelectOptGroup` 在渲染期解析，支持条件 slot、`v-if`、`v-for` 和动态 value/label/disabled。显式 `options` 优先于默认插槽，包括 `options=[]`；切回 `undefined` 才使用插槽。临时移除已选项时保留其标签缓存，选项恢复后使用最新标签。无需更换组件 key，输入节点和选择状态保持。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value / defaultValue | 受控值（`v-model:value`）/ 非受控初值 | `SelectValue` | — |
| searchValue | 受控搜索词（`v-model:search-value`） | `string` | `''` |
| mode | 模式 | `'multiple' \| 'tags'` | 单选 |
| options | 选项数据（支持嵌套分组） | `DefaultOptionType[]` | — |
| labelInValue | `change/select/deselect` 输出 `{ label, value }` | `boolean` | `false` |
| showSearch | 可搜索；对象形态配置过滤 | `boolean \| SearchConfig` | `false` |
| filterOption | 自定义过滤（⚠️ 默认按 `value` 匹配，大小写不敏感） | `boolean \| fn` | — |
| optionFilterProp | 过滤字段（传 `string[]` 多字段 OR） | `string \| string[]` | `'value'` |
| filterSort | 过滤结果排序 | `fn` | — |
| allowClear | 清除按钮（`{ clearIcon, label }` 定制） | `boolean \| object` | `false` |
| placeholder | 占位文本（富内容用 `#placeholder` 插槽） | `string` | — |
| size | 尺寸（= `SizeType`，含 `medium`） | `'small' \| 'medium' \| 'middle' \| 'large'` | `'middle'` |
| variant | 变体 | `'outlined' \| 'filled' \| 'borderless' \| 'underlined'` | `'outlined'` |
| status | 校验状态 | `'error' \| 'warning' \| 'success' \| 'validating'` | — |
| disabled / loading | 禁用 / 加载中 | `boolean` | `false` |
| maxCount | 最多可选数（仅多选/标签） | `number` | — |
| maxTagCount / maxTagTextLength | 多选折叠 / 文本截断 | `number` | — |
| tokenSeparators | 自动分词分隔符（数组或函数） | `string[] \| fn` | — |
| listHeight / listItemHeight | 列表最大高 / 估算行高 | `number` | `256 / 32` |
| popupMatchSelectWidth | 浮层宽度跟随触发器 | `boolean \| number` | `true` |
| placement | 弹出位置 | 4 值 | `'bottomLeft'` |
| open / defaultOpen | 受控开合（`v-model:open`） | `boolean` | `false` |
| fieldNames / optionLabelProp | 字段映射 / 回填字段 | — | `label` |
| virtual | 虚拟滚动 | `boolean` | `true` |
| classNames / styles | 语义槽 `root/prefix/suffix/input/placeholder/content/item/itemContent/itemRemove/clear/popup.{root,list,listItem}` | — | — |
| dropdownClassName / dropdownStyle / dropdownMatchSelectWidth / popupClassName / bordered / showArrow 等 | ⚠️ 已废弃 | — | — |

搜索配置只包含 `filterOption`、`filterSort`、`optionFilterProp`、`autoClearSearchValue`；通知使用 `@search`，搜索图标使用 `#searchIcon`。筛选、排序、分词和浮层容器函数保留其业务职责。`showSearch.onSearch/searchValue/searchIcon` 不再是配置通道。

`value`、`searchValue`、`open` 的受控更新是提议；父级拒绝后保持当前值，撤控保留最后接受值。`defaultValue/defaultOpen` 仅作初值。`labelInValue` 开启时单项事件的值为 `{ value, label }`，否则为 `string | number`。

### Events

| 事件 | 说明 | 参数 |
|---|---|---|
| change | 值变化（与 `update:value` 同发） | `(value, option)` |
| select / deselect | 选中 / 取消选中一项 | `(value, option)` |
| search | 输入产生的搜索通知 | `(value: string)` |
| update:searchValue | 搜索词更新提议（含选中后清空） | `(value: string)` |
| openChange / update:open | 开合通知 / 模型提议 | `(open: boolean)` |
| focus / blur | 焦点 | `(event)` |
| clear | 点击清除 | — |
| popupScroll | 下拉滚动 | `(event: Event)` |
| inputKeyDown | 搜索框按键 | `(event: KeyboardEvent)` |

### Slots

`prefix` / `suffixIcon="{ searchValue, open, focused, showSearch, loading }"` / `searchIcon` / `loadingIcon` / `clearIcon` / `removeIcon` / `placeholder` /
`notFoundContent` / `optionRender="{ option, index }"` / `tagRender` / `labelRender` /
`popupRender="{ menu }"` / `maxTagPlaceholder="{ omittedValues }"` /
`menuItemSelectedIcon="{ value, disabled, isSelected }"` /
`default`（`Select.Option` / `Select.OptGroup` 子组件形态，deprecated 但支持）。

> ⚠️ antd 的 ReactNode props（`suffixIcon` / `notFoundContent` / `optionRender` /
> `maxTagPlaceholder` 等）在本仓**一律是作用域插槽**，不保留同名 prop（规则 C8-R2）。

插槽在 render 中读取，动态加入、替换或移除会立即更新；提供空插槽表示有意隐藏，不回退默认内容，数字 `0` 正常显示。`#loadingIcon/#searchIcon` 在对应状态优先，`#suffixIcon` 控制其余 suffix 展示并收到真实焦点。`options` 内的 `label` 与图标配置仍是数据内容，顶层内容函数只通过插槽扩展。

### Attrs、Provider 与主题

原生 `class/style` 落选择器根容器；`id/tabindex/role/aria-*` 落实际 input，`data-*` 和其余原生 attrs 落根容器，监听器与内部交互合并。`focus/blur` 是组件焦点通知。样式优先级为当前主题 → Provider `style` → Provider/局部 `styles.root` → 原生 `style`；语义类名拼接。

当前、嵌套与移除后的 ConfigProvider 配置响应式生效；Select Token 同时写到根和 Teleport 浮层，虚拟列表估算行高跟随 `optionHeight`。使用复杂 CSS 行高时通过 `listItemHeight` 给出数值估算。`SelectPurePanel` 使用同一 Props、Slots、Emits 和 Ref，在自身容器中展开浮层并占据布局。

### Methods

| 方法 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| focus | 聚焦 | `(options?: FocusOptions)` | — |
| blur | 失焦 | — | — |
| scrollTo | 滚动到坐标或指定项 | `(scrollTop \| { index, align, key })` | — |
| nativeElement | 根元素 | — | `HTMLElement` |

## 设计说明

- **rc-select 1.10.1 内核的 Vue 自建**（engine/ 五层）；DOM 无 `-selector` 包裹层（v6）。
- 与 antd 的已知差异见组件 README。
- ⚠️ 搜索默认按 `value` 匹配 —— 按 label 搜请传 `showSearch: { optionFilterProp: 'label' }`。


## 条件与动态选项 (conditional-options)

默认插槽可通过 `v-if` 出现/移除，`SelectOption` 支持 `v-for`、分组与动态 label/disabled。已选条目暂时移除时保留标签；重新出现时使用最新内容。无需通过 key 重建组件。

The default option slot supports conditional insertion/removal, loops, groups and reactive labels/disabled state. Selected labels remain cached when options disappear and refresh when they return. No component key or remount is needed.

### conditional-options.vue

```vue
<script setup lang="ts">
import {
  AutoComplete,
  Button,
  Flex,
  Select,
  SelectOptGroup,
  SelectOption,
} from '@apollo-design/ui';
import { ref } from 'vue';

const show = ref(false);
const value = ref<string>('a');
const suggestion = ref<string>();
const choices = ref([
  { value: 'a', label: 'Alpha', disabled: false },
  { value: 'b', label: 'Beta', disabled: false },
]);
const update = () => {
  choices.value = [
    { value: 'a', label: 'Updated Alpha', disabled: false },
    { value: 'b', label: 'Disabled Beta', disabled: true },
    { value: 'c', label: 'Gamma', disabled: false },
  ];
};
</script>

<template>
  <Flex vertical gap="small" align="flex-start">
    <Flex gap="small" wrap>
      <Button @click="show = !show">显示/隐藏选项 / Toggle options</Button>
      <Button :disabled="!show" @click="update">更新选项 / Update options</Button>
    </Flex>
    <label for="conditional-select">选择 / Select</label>
    <Select id="conditional-select" v-model:value="value" show-search option-filter-prop="children" style="width: 240px">
      <template v-if="show" #default>
        <SelectOptGroup label="Group">
          <SelectOption v-for="choice in choices" :key="choice.value" :value="choice.value" :disabled="choice.disabled">{{ choice.label }}</SelectOption>
        </SelectOptGroup>
      </template>
    </Select>
    <output aria-live="polite">{{ value }}</output>
    <label for="conditional-autocomplete">自动补全 / AutoComplete</label>
    <AutoComplete id="conditional-autocomplete" v-model:value="suggestion" style="width: 240px">
      <template v-if="show" #default>
        <SelectOptGroup label="Group">
          <SelectOption v-for="choice in choices" :key="choice.value" :value="choice.value" :disabled="choice.disabled">{{ choice.label }}</SelectOption>
        </SelectOptGroup>
      </template>
    </AutoComplete>
  </Flex>
</template>
```

## automatic-tokenization (automatic-tokenization)

`tokenSeparators`：输入 `,` 自动切分成标签。

### automatic-tokenization.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/automatic-tokenization.tsx
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string[]>([]);
const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <Select
    v-model:value="value"
    mode="tags"
    :options="options"
    :token-separators="[',']"
    style="width: 100%"
  />
</template>
```

## basic (basic)

基础单选。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic.tsx
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string | undefined>('a1');

const options = [
  { value: 'a1', label: '杰克' },
  { value: 'b2', label: '露西' },
  { value: 'c3', label: '汤姆' },
  { value: 'd4', label: '杰瑞' },
];
</script>

<template>
  <Select v-model:value="value" :options="options" style="width: 120px" />
</template>
```

## big-data (big-data)

10000 条选项，默认开启虚拟滚动。

### big-data.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/big-data.tsx：1 万条选项走虚拟滚动
import { Select } from '@apollo-design/ui';

const options = Array.from({ length: 10000 }, (_, i) => ({
  value: String(i),
  label: `option ${i}`,
}));
</script>

<template>
  <Select :options="options" show-search style="width: 200px" placeholder="10,000 options" />
</template>
```

## clear-suffix-debug (clear-suffix-debug)

调试用例：清除按钮与自定义后缀共存。

### clear-suffix-debug.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/clear-suffix-debug.tsx
import { DownOutlined } from '@apollo-design/icons';
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref('a1');
const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <div>
    <Select v-model:value="value" :options="options" allow-clear style="width: 200px">
      <template #suffixIcon><DownOutlined /></template>
    </Select>
    <p>value: {{ value ?? 'null' }}</p>
  </div>
</template>
```

## native-models (native-models)

值、搜索词与开合分别使用 `v-model:value`、`v-model:search-value` 和 `v-model:open`。内容扩展使用具名插槽，作用域提供当前开合与焦点状态。

### native-models.vue

```vue
<script setup lang="ts">
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string>();
const searchValue = ref('');
const open = ref(false);
const options = [
  { value: 'a', label: 'Apple' },
  { value: 'b', label: 'Banana' },
];
</script>

<template>
  <Select
    v-model:value="value"
    v-model:search-value="searchValue"
    v-model:open="open"
    :show-search="{ optionFilterProp: 'label' }"
    :options="options"
    aria-label="Choose a fruit"
    style="width: 240px"
  >
    <template #suffixIcon="{ open: expanded, focused }">{{ expanded ? '↑' : focused ? '•' : '↓' }}</template>
    <template #searchIcon>⌕</template>
  </Select>
  <p>Value: {{ value ?? '—' }} · Search: {{ searchValue || '—' }} · Open: {{ open }}</p>
</template>
```

## component-token (component-token)

通过 ConfigProvider 覆盖 Select 的 Component Token。

### component-token.vue

```vue
<script setup lang="ts">
import { Checkbox, ConfigProvider, Flex, Select } from '@apollo-design/ui';
import { ref } from 'vue';

const largeOptions = ref(false);
const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <Flex vertical gap="small" align="start">
    <Checkbox v-model:checked="largeOptions">Taller options</Checkbox>
  <ConfigProvider
    :theme="{
      components: { Select: { optionHeight: largeOptions ? 52 : 40, selectorBg: 'color-mix(in srgb, #52c41a 10%, var(--apollo-color-bg-container))', optionSelectedBg: 'color-mix(in srgb, #52c41a 24%, var(--apollo-color-bg-container))' } },
    }"
  >
    <Select :options="options" default-value="a1" aria-label="Themed choices" style="width: 200px" />
  </ConfigProvider>
  </Flex>
</template>
```

## coordinate (coordinate)

两个 Select 联动选择坐标（antd 原例经 hooks 通信，此处以 v-model 等价实现）。

### coordinate.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/coordinate.tsx：两个 Select 联动选坐标（Vue 写法等价替换）
import { Select } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const x = ref<number | undefined>(1);
const y = ref<number | undefined>(1);
const list = [1, 2, 3, 4];
const result = computed(() => `(${x.value ?? '-'}, ${y.value ?? '-'})`);
</script>

<template>
  <div style="display: flex; gap: 8px; align-items: center">
    <Select v-model:value="x" :options="list.map((v) => ({ value: v, label: `x${v}` }))" style="width: 90px" />
    <Select v-model:value="y" :options="list.map((v) => ({ value: v, label: `y${v}` }))" style="width: 90px" />
    <span>{{ result }}</span>
  </div>
</template>
```

## custom-dropdown-menu (custom-dropdown-menu)

`#popupRender` 在下拉菜单末尾追加 Apollo 按钮，点击后即时添加一个选项，并保留搜索输入焦点。

### custom-dropdown-menu.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/custom-dropdown-menu.tsx（popupRender 作用域插槽，在菜单末尾追加内容）
import { Button, Select } from '@apollo-design/ui';
import { defineComponent, h, type PropType, ref, type VNodeChild } from 'vue';

const options = ref([
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
]);

function addItem(): void {
  const index = options.value.length + 1;
  options.value.push({ value: `custom-${index}`, label: `Item ${index}` });
}

/** demo 局部辅助：在模板里渲染一个 VNode（Vue 模板没有 h() 的直接入口）。 */
const RenderVNode = defineComponent({
  props: { node: { type: null as unknown as PropType<VNodeChild>, default: undefined } },
  setup: (props) => () => props.node,
});
</script>

<template>
  <Select :options="options" style="width: 200px">
    <template #popupRender="{ menu }">
      <div>
        <RenderVNode :node="menu" />
        <div style="padding: 8px"><Button @mousedown.prevent @click="addItem">Add item</Button></div>
      </div>
    </template>
  </Select>
</template>
```

## custom-label-render (custom-label-render)

`labelRender` 自定义回填内容的渲染。

### custom-label-render.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/custom-label-render.tsx（labelRender 作用域插槽）
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'gold', label: 'Gold' },
  { value: 'lime', label: 'Lime' },
];
</script>

<template>
  <Select :options="options" style="width: 200px">
    <template #labelRender="{ label, value }">
      <span style="font-weight: bold">{{ label ?? value }} (custom)</span>
    </template>
  </Select>
</template>
```

## custom-tag-render (custom-tag-render)

`tagRender` 作用域插槽自定义多选标签。

### custom-tag-render.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/custom-tag-render.tsx（tagRender 作用域插槽，prop 优先）
import { Select, Tag } from '@apollo-design/ui';

const options = [
  { value: 'gold', label: 'Gold' },
  { value: 'lime', label: 'Lime' },
];
</script>

<template>
  <Select mode="multiple" :options="options" style="width: 100%">
    <template #tagRender="{ label, value, closable, onClose }">
      <Tag :closable="closable" style="margin-inline-end: 4px" @close="onClose">
        {{ label }} ({{ value }})
      </Tag>
    </template>
  </Select>
</template>
```

## custom-tokenization (custom-tokenization)

`tokenSeparators` 支持函数形态，自定义切分规则。

### custom-tokenization.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/custom-tokenization.tsx（函数形态 tokenSeparators）
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string[]>([]);
const options = [{ value: 'a1', label: 'Jack' }];
const tokenize = (input: string): string[] =>
  input
    .split(/[;,]/)
    .map((part) => part.trim())
    .filter(Boolean);
</script>

<template>
  <Select
    v-model:value="value"
    mode="tags"
    :options="options"
    :token-separators="tokenize"
    style="width: 100%"
  />
</template>
```

## debug (debug)

调试用例：清除 + 搜索组合。

### debug.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/debug.tsx
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string | undefined>();
const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <Select v-model:value="value" :options="options" allow-clear show-search style="width: 200px" />
</template>
```

## debug-flip-shift (debug-flip-shift)

调试用例：空间不足时翻转。

### debug-flip-shift.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/debug-flip-shift.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <div style="height: 60px">
    <Select :options="options" placement="topLeft" style="width: 200px" />
  </div>
</template>
```

## filled-debug (filled-debug)

调试用例：`filled` 变体。

### filled-debug.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/filled-debug.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <Select :options="options" variant="filled" style="width: 200px" />
</template>
```

## hide-selected (hide-selected)

过滤掉已选项（antd 原例为自定义 filterOption，此处同样实现）。

### hide-selected.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/hide-selected.tsx

import type { DefaultOptionType } from '@apollo-design/ui';
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string[]>([]);
const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
  { value: 'c3', label: 'Tom' },
];
</script>

<template>
  <Select
    v-model:value="value"
    mode="multiple"
    :options="options"
    :show-search="{
      filterOption: (i: string, o?: DefaultOptionType) => !value.includes(String(o?.value)),
    }"
    style="width: 100%"
  />
</template>
```

## label-in-value (label-in-value)

`labelInValue`：`onChange` 收到 `{ label, value }`。

### label-in-value.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/label-in-value.tsx
import { Select, type SelectValue } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<SelectValue>({
  value: 'a1',
  label: 'Jack',
});

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <div>
    <Select v-model:value="value" label-in-value :options="options" style="width: 200px" />
    <p>{{ value }}</p>
  </div>
</template>
```

## max-count (max-count)

`maxCount` 限制最多可选 2 项（仅 multiple / tags）。

### max-count.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/maxCount.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
  { value: 'c3', label: 'Tom' },
];
</script>

<template>
  <Select mode="multiple" :options="options" :max-count="2" style="width: 100%" />
</template>
```

## multiple (multiple)

多选，`value` 为数组。

### multiple.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/multiple.tsx
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string[]>(['a1', 'b2']);

const options = [
  { value: 'a1', label: '杰克' },
  { value: 'b2', label: '露西' },
  { value: 'c3', label: '汤姆' },
];
</script>

<template>
  <Select v-model:value="value" mode="multiple" :options="options" style="width: 100%" />
</template>
```

## optgroup (optgroup)

用嵌套 `options` 展示分组（`Select.OptGroup` 子组件形态同样支持）。

### optgroup.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/optgroup.tsx（options 分组形态）
import { Select } from '@apollo-design/ui';

const options = [
  {
    label: 'Manager',
    options: [
      { value: 'jack', label: 'Jack' },
      { value: 'lucy', label: 'Lucy' },
    ],
  },
  { label: 'Engineer', options: [{ value: 'tom', label: 'Tom' }] },
];
</script>

<template>
  <Select :options="options" style="width: 120px" />
</template>
```

## option-label-center (option-label-center)

选项内容居中展示。

### option-label-center.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/option-label-center.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <Select :options="options" style="width: 200px">
    <template #optionRender="{ option }">
      <div style="text-align: center">{{ option.label }}</div>
    </template>
  </Select>
</template>
```

## option-render (option-render)

`optionRender` 作用域插槽自定义下拉选项内容。

### option-render.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/option-render.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'gold', label: 'Gold' },
  { value: 'lime', label: 'Lime' },
];
</script>

<template>
  <Select :options="options" style="width: 200px">
    <template #optionRender="{ option }">
      <div style="display: flex; justify-content: space-between">
        <span>{{ option.label }}</span>
        <span style="color: var(--apollo-color-text-secondary)">custom</span>
      </div>
    </template>
  </Select>
</template>
```

## placement (placement)

四种弹出位置。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/placement.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px">
    <Select :options="options" placement="topLeft" style="width: 200px" placeholder="topLeft" />
    <Select :options="options" placement="topRight" style="width: 200px" placeholder="topRight" />
    <Select :options="options" placement="bottomLeft" style="width: 200px" placeholder="bottomLeft" />
    <Select :options="options" placement="bottomRight" style="width: 200px" placeholder="bottomRight" />
  </div>
</template>
```

## placement-debug (placement-debug)

调试用例：受控展开。

### placement-debug.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/placement-debug.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <Select :options="options" open style="width: 200px" />
</template>
```

## render-panel (render-panel)

`Select._InternalPanelDoNotUseOrYouWillBeFired` 的对应物：静态面板。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/render-panel.tsx
import { Select, SelectPurePanel } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <SelectPurePanel :options="options" />
</template>
```

## responsive (responsive)

多选溢出折叠为 `+N ...`（antd 原例为 `maxTagCount="responsive"`，本仓以固定值等价展示，见 README）。

### responsive.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/responsive.tsx（⚠️ responsive 折叠依赖 ResizeObserver 测量，
// 本轮以固定 maxTagCount 等价替换，见 README §2）
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
  { value: 'c3', label: 'Tom' },
];
</script>

<template>
  <Select mode="multiple" :options="options" :max-tag-count="2" style="width: 100%" />
</template>
```

## search (search)

搜索框：`showSearch` + 按 `label` 过滤（注意默认按 `value` 过滤）。

### search.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/search.tsx（⚠️ optionFilterProp 默认按 value，此处显式指定 label）
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string | undefined>();
const search = ref('');

const options = [
  { value: 'a1', label: 'Not Identified' },
  { value: 'b2', label: 'Closed' },
  { value: 'c3', label: 'Communicated' },
];
const onSearch = (v: string): void => {
  search.value = v;
};
</script>

<template>
  <div>
    <Select
      v-model:value="value"
      :options="options"
        :show-search="{ optionFilterProp: 'label' }"
      style="width: 200px"
      @search="onSearch"
    />
    <p>search: {{ search }}</p>
  </div>
</template>
```

## search-filter-option (search-filter-option)

自定义过滤函数 `filterOption`。

### search-filter-option.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/search-filter-option.tsx

import type { DefaultOptionType } from '@apollo-design/ui';
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Not Identified' },
  { value: 'b2', label: 'Closed' },
  { value: 'c3', label: 'Communicated' },
];
const filterOption = (input: string, option?: DefaultOptionType): boolean =>
  String(option?.label ?? '')
    .toLowerCase()
    .includes(input.toLowerCase());
</script>

<template>
  <Select :options="options" show-search :filter-option="filterOption" style="width: 200px" />
</template>
```

## search-multi-field (search-multi-field)

`optionFilterProp` 传数组时对多个字段做 OR 匹配。

### search-multi-field.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/search-multi-field.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack', nick: 'J' },
  { value: 'b2', label: 'Lucy', nick: 'L' },
];
</script>

<template>
  <Select
    :options="options"
    :show-search="{ optionFilterProp: ['label', 'nick'] }"
    style="width: 200px"
  />
</template>
```

## search-sort (search-sort)

搜索结果按 `filterSort` 排序。

### search-sort.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/search-sort.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Not Identified' },
  { value: 'b2', label: 'Closed' },
  { value: 'c3', label: 'Communicated' },
];
const filterSort = (a: { label?: unknown }, b: { label?: unknown }): number =>
  String(a.label ?? '').localeCompare(String(b.label ?? ''));
</script>

<template>
  <Select
    :options="options"
    :show-search="{ optionFilterProp: 'label', filterSort }"
    style="width: 200px"
  />
</template>
```

## select-users (select-users)

已选用户列表（antd 原例经 hooks 通信，此处以 v-model 等价实现）。

### select-users.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/select-users.tsx（tagRender + 已选列表，Vue 等价替换）
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string[]>([]);
const options = [
  { value: 'jack', label: 'Jack' },
  { value: 'lucy', label: 'Lucy' },
  { value: 'tom', label: 'Tom' },
];
</script>

<template>
  <div>
    <Select
      v-model:value="value"
      mode="multiple"
      :options="options"
      style="width: 100%"
    />
    <p>已选：{{ value.join(', ') || '无' }}</p>
  </div>
</template>
```

## size (size)

三种尺寸：`small` / `middle` / `large`。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/size.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: '杰克' },
  { value: 'b2', label: '露西' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px">
    <Select :options="options" size="small" style="width: 120px" placeholder="small" />
    <Select :options="options" style="width: 120px" placeholder="middle" />
    <Select :options="options" size="large" style="width: 120px" placeholder="large" />
  </div>
</template>
```

## status (status)

校验状态：`error` / `warning`。

### status.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/status.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: '杰克' },
  { value: 'b2', label: '露西' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px">
    <Select :options="options" status="error" style="width: 120px" placeholder="error" />
    <Select :options="options" status="warning" style="width: 120px" placeholder="warning" />
  </div>
</template>
```

## style-class (style-class)

语义化 `classNames` / `styles`。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx（语义 classNames / styles）
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <Select
    :options="options"
    style="width: 200px"
    :class-names="{ root: 'demo-root', suffix: 'demo-suffix' }"
    :styles="{ content: { color: 'red' } }"
  />
</template>
```

## suffix (suffix)

自定义后缀图标。

### suffix.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/suffix.tsx
import { MoneyCollectOutlined } from '@apollo-design/icons';
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: 'Jack' },
  { value: 'b2', label: 'Lucy' },
];
</script>

<template>
  <Select :options="options" style="width: 200px">
    <template #suffixIcon><MoneyCollectOutlined /></template>
  </Select>
</template>
```

## tags (tags)

标签模式，输入后回车即可创建新标签。

### tags.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/tags.tsx
import { Select } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<string[]>(['a1', 'b2']);

const options = [
  { value: 'a1', label: '杰克' },
  { value: 'b2', label: '露西' },
];
</script>

<template>
  <Select v-model:value="value" mode="tags" :options="options" style="width: 100%" />
</template>
```

## variant (variant)

四种变体：`outlined` / `filled` / `borderless` / `underlined`。

### variant.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/variant.tsx
import { Select } from '@apollo-design/ui';

const options = [
  { value: 'a1', label: '杰克' },
  { value: 'b2', label: '露西' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px">
    <Select :options="options" variant="outlined" style="width: 120px" placeholder="outlined" />
    <Select :options="options" variant="filled" style="width: 120px" placeholder="filled" />
    <Select :options="options" variant="borderless" style="width: 120px" placeholder="borderless" />
    <Select :options="options" variant="underlined" style="width: 120px" placeholder="underlined" />
  </div>
</template>
```

---

# Skeleton

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/skeleton


# Skeleton 骨架屏

按预期结构显示加载占位。`loading`由调用者控制；组件不发请求，也不自动完成加载。

## 代码演示

原八个示例保留，并新增可切换主题与原生变量的示例。查看加载开关、独立元素、完整内容和当前组件Token。

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Skeleton } from '@apollo-design/ui';
const loading = ref(true);
const draft = ref('保留业务数据');
</script>
<template>
  <button type="button" @click="loading = !loading">切换加载</button>
  <Skeleton :loading="loading" avatar>
    <input v-model="draft" aria-label="业务输入" />
  </Skeleton>
</template>
```

## API

### Skeleton Props

| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| active | 微光动画，遵守减少动画与源motion:false | boolean | false |
| loading | 只有false显示真实内容；未传/undefined均显示骨架 | boolean | — |
| prefixCls | 当前类名前缀 | string | apollo-skeleton |
| avatar | 头像块及单元素配置 | boolean / SkeletonAvatarProps | false |
| title | 标题块配置 | boolean / SkeletonTitleProps | true |
| paragraph | 段落块配置 | boolean / SkeletonParagraphProps | true |
| round | 标题与段落使用胶囊圆角 | boolean | false |
| classNames | 六语义落点的类；函数读取当前`{ props }` | SkeletonSemanticValue&lt;SkeletonSemanticClassNames&gt; | — |
| styles | 六语义落点的样式；函数读取当前`{ props }` | SkeletonSemanticValue&lt;SkeletonSemanticStyles&gt; | — |

### 独立子组件 Props

具名`SkeletonAvatar/SkeletonButton/SkeletonInput/SkeletonImage/SkeletonNode`与静态`Skeleton.Avatar/Button/Input/Image/Node`指向同一组件。

| 属性 | 适用 | 说明 |
|---|---|---|
| prefixCls | 全部 | 当前前缀 |
| active | 全部 | 微光动画，默认false |
| classNames / styles | 全部 | 对象形式，root为外层div，content为内层占位/内容 |
| size | Avatar | small / medium / middle / large / 既有default别名 / 非负有限像素数；默认取Provider componentSize |
| shape | Avatar | circle（默认）/ square |
| size | Button / Input | small / medium / middle / large / 既有default别名；默认取Provider componentSize |
| shape | Button | circle / square / round / default；缺省不加形状类 |
| block | Button / Input | 撑满一行，默认false |
| internalClassName | Node | 已有内容类覆盖；空值使用默认node类，Image内部用它选择image类 |

`size="default"`仍保留既有废弃告警，使用medium。根className别名已移除；内层尺寸/样式使用`styles.content`。

### 块配置

avatar/title/paragraph配置中的`prefixCls/className/style`是数据字段，保留并与对应语义合并；语义样式最后覆盖配置style，类拼接。

| 字段 | 适用 | 说明 |
|---|---|---|
| size / shape | avatar | 尺寸与circle/square；默认large，存在title且无paragraph时为square，否则circle |
| width | title | 数字像素或CSS字符串；无头像且有段落时38%，两者都有时50%，否则不设 |
| rows | paragraph | 默认无头像且有title时3，否则2；非有限/负值为空，有限正小数截断 |
| width | paragraph | 数组逐行，单值只作用最后一行；无头像或无title时默认末行61% |

非有限数值长度忽略，0保留。avatar是单个占位元素，使用主`classNames.avatar/styles.avatar`，不接受独立双层组件的classNames/styles配置。

### 原生 attrs、Provider与优先级

六组件的id/data/ARIA/tabindex/原生事件均落真实根。Vue字符串、数组、对象class/style有效；原生样式最后覆盖，子组件content使用独立语义落点。主`loading=false`没有根，attrs不会复制到业务槽；需要持久宿主时自行包裹。

主组件读取当前`components.skeleton`的className/style/classNames/styles，配置替换、删除和恢复即时生效。五个子组件消费全局前缀、适用尺寸和源主题；主六槽配置不套入子组件两槽。最近Provider与实例隔离，RTL即时更新。任意自定义前缀仍需对应静态CSS。

### Slots / Emits / v-model

| 组件 / 槽 | 说明 |
|---|---|
| Skeleton default | loading=false时直接渲染完整真实内容，无包裹 |
| SkeletonNode default | 当前完整自定义内容，原生编辑器不会因周边样式/主题改变重挂 |
| SkeletonImage default | 有槽时优先，含有意空槽；无槽显示原内置SVG |

无业务emits或v-model，loading受控。原生监听收到DOM事件。主六语义落点为root/header/section/avatar/title/paragraph；子组件为root/content。

### Expose

仅主Skeleton公开`nativeElement: HTMLDivElement | null`。loading=false或卸载后为null。正文loading开关时会卸载，数据应保存在调用者响应状态中；不承诺卸载后的节点或焦点身份。

### 组件Token

全部形态读取当前`theme.components.Skeleton`，移除/恢复响应；现代渐变字段优先既有别名，再回退当前Alias。对应`--apollo-skeleton-*`变量可在根原生style覆盖。

| Token | 类型 | 默认来源 |
|---|---|---|
| gradientFromColor | string | colorFillContent |
| gradientToColor | string | colorFill |
| color（既有deprecated别名）| string | gradientFromColor |
| colorGradientEnd（既有deprecated别名）| string | gradientToColor |
| titleHeight | number / CSS长度string | controlHeight / 2 |
| blockRadius | number | borderRadiusSM |
| paragraphMarginTop | number | marginLG + marginXXS |
| paragraphLiHeight | number | controlHeight / 2 |

### 无障碍、SSR与样式

加载根为aria-busy=true，header/section装饰内容aria-hidden，空占位标题不进入可访问树；可通过原生attrs提供role/名称。Node/Image真实槽内容保持可访问，内置SVG为装饰图。active遵守prefers-reduced-motion与源motion:false，不自动加live播报。

SSR不依赖window；默认槽和当前主题在服务端可渲染，水合与生产浏览器验收状态以完整清单为准。样式入口：`@apollo-design/ui/skeleton/style.css`。破坏性变更和旧/新写法见仓库`docs/migrations/skeleton-contracts.md`；本轮实际命令、证据与未验边界见`docs/audit/2026-10-27-skeleton-contract-audit.md`。


## 基础 (basic)

不传任何 props 时的默认形态：`avatar` 为 `false`、`title` 与 `paragraph` 均为 `true`。
所以**只有 `-section`、没有 `-header`**，段落默认 3 行。

### basic.vue

```vue
<script setup lang="ts">
import { Skeleton } from '@apollo-design/ui';
</script>

<template>
  <Skeleton />
</template>
```

## 带头像 (avatar)

`avatar` 为真时多出一个 `-header` 容器（与 `-section` **并列**，不是嵌套）。

⚠️ 头像的形状由**另外两项**推导：`hasTitle && !hasParagraph` 时是**方形**，
否则是圆形；`size` 恒为 `large`。本示例关掉了段落，所以是方形。

### avatar.vue

```vue
<script setup lang="ts">
import { Skeleton } from '@apollo-design/ui';
</script>

<template>
  <Skeleton avatar :paragraph="false" />
</template>
```

## 加载完成前显示骨架 (loading)

`loading` 是**三态**：未传与 `true` 都显示骨架，**只有 `false` 显示子内容**。

由调用者维护loading状态；业务正文切换时会卸载，需持久的输入数据放在父级响应状态中。

### loading.vue

```vue
<script setup lang="ts">
import { Button, Skeleton } from '@apollo-design/ui';
import { ref } from 'vue';

const loading = ref(true);
</script>

<template>
  <div>
    <Button style="margin-bottom: 16px" @click="loading = !loading">切换（当前 {{ loading ? '骨架' : '内容' }}）</Button>
    <Skeleton :loading="loading">
      <div>这是真实内容。</div>
    </Skeleton>
  </div>
</template>
```

## 动画与圆角 (active)

`active` 让灰块有呼吸动画；`round` 把标题与段落的圆角拉到「胶囊」级别
（`-round` 是**根元素**上的类名，作用于后代的标题/段落）。

### active.vue

```vue
<script setup lang="ts">
import { Flex, Skeleton } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical gap="large">
    <Skeleton active />
    <Skeleton active round />
  </Flex>
</template>
```

## 语义化样式 (semantic)

`classNames` / `styles` 各支持 6 个键，与 DOM 结构一一对应：
`root` / `header` / `section` / `avatar` / `title` / `paragraph`。

主组件同时支持对象与函数，函数读取当前`{ props }`；原生`class/style`作用于根，区块配置的class/style与对应语义配置合并。

### semantic.vue

```vue
<script setup lang="ts">
import { Skeleton } from '@apollo-design/ui';
</script>

<template>
  <Skeleton
    avatar
    :class-names="{ root: 'demo-root', avatar: 'demo-avatar', paragraph: 'demo-paragraph' }"
    :styles="{ paragraph: { marginBlockStart: '24px' } }"
  />
</template>
```

## 当前组件主题 (component-token)

六种骨架形态共享当前源主题。切换主题、动画或原生标题高度变量，输入值与焦点保持；内容样式使用`styles.content`，普通`style`作用于根。

All six shapes follow the current source theme. Theme and native-variable changes preserve the editor; `styles.content` targets the inner content and native `style` targets the root.

### component-token.vue

```vue
<script setup lang="ts">
import {
  Button,
  Checkbox,
  ConfigProvider,
  Input,
  Skeleton,
  SkeletonAvatar,
  SkeletonButton,
  SkeletonImage,
  SkeletonInput,
  SkeletonNode,
} from '@apollo-design/ui';
import { computed, ref } from 'vue';

const themed = ref(true),
  native = ref(false),
  active = ref(true),
  draft = ref('Native Skeleton draft');
const theme = computed(() =>
  themed.value
    ? {
        components: {
          Skeleton: {
            gradientFromColor: '#dce8ff',
            gradientToColor: '#91b2ff',
            titleHeight: 22,
            blockRadius: 8,
            paragraphMarginTop: 30,
            paragraphLiHeight: 18,
          },
        },
      }
    : undefined,
);
</script>
<template>
  <div style="display:flex;flex-wrap:wrap;gap:8px;margin-bottom:16px">
    <Button @click="themed = !themed">Toggle Skeleton theme</Button>
    <Button @click="native = !native">Toggle native Skeleton variable</Button>
    <Checkbox v-model:checked="active">Active</Checkbox>
  </div>
  <ConfigProvider :theme="theme">
    <Skeleton avatar :active="active" :style="native ? { '--apollo-skeleton-title-height': '30px' } : undefined" />
    <div style="display:flex;flex-wrap:wrap;align-items:center;gap:16px;margin-top:16px">
      <SkeletonAvatar :active="active" />
      <SkeletonButton :active="active" />
      <SkeletonInput :active="active" />
      <SkeletonImage :active="active" />
    </div>
    <SkeletonNode :styles="{ root: { display: 'block', marginTop: '16px' }, content: { width: '100%', minHeight: '70px', padding: '16px', color: themed ? '#172b4d' : undefined } }">
      <label style="display:flex;flex-wrap:wrap;align-items:center;gap:8px">Persistent draft<Input v-model:value="draft" aria-label="Skeleton token draft" style="max-width:100%;width:180px" /></label>
    </SkeletonNode>
  </ConfigProvider>
</template>
```

## 包含子内容 (children)

`loading` 为 `true` 时显示骨架，为 `false` 时只渲染默认插槽；点击按钮模拟一次加载。

### children.vue

```vue
<script setup lang="ts">
// 调用者拥有加载状态；持久外层承接两种分支的布局间距。
import { Button, Skeleton } from '@apollo-design/ui';
import { onBeforeUnmount, ref } from 'vue';

const loading = ref(false);

let timer: ReturnType<typeof setTimeout> | undefined;
const reload = () => {
  if (timer !== undefined) clearTimeout(timer);
  loading.value = true;
  timer = setTimeout(() => {
    timer = undefined;
    loading.value = false;
  }, 800);
};
onBeforeUnmount(() => {
  if (timer !== undefined) clearTimeout(timer);
});
</script>

<template>
  <Button :disabled="loading" @click="reload">{{ loading ? '加载中…' : '重新加载' }}</Button>
  <div style="margin-top:16px">
    <Skeleton :loading="loading" avatar :paragraph="{ rows: 3 }">
      <div>
        <strong>张三</strong>
        <p>这是加载完成后显示的真实内容；`loading` 为 false 时只渲染默认插槽。</p>
      </div>
    </Skeleton>
  </div>
</template>
```

## 复杂组合 (complex)

`Skeleton.Node` 承载自定义占位内容，与带 `avatar` / `paragraph` 的 `Skeleton` 组合成卡片骨架；按钮切换 `active`。

### complex.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 complex demo：Skeleton.Node 自定义占位内容
import { PictureOutlined } from '@apollo-design/icons';
import { Button, Skeleton } from '@apollo-design/ui';
import { ref } from 'vue';

const active = ref(true);

const toggle = () => {
  active.value = !active.value;
};
</script>

<template>
  <Button @click="toggle">{{ active ? '关闭微光动画' : '开启微光动画' }}</Button>
  <div style="display: flex; flex-wrap: wrap; gap: 16px; margin-top: 16px">
    <Skeleton.Node :active="active" :styles="{ content: { width: '160px', height: '120px' } }">
      <PictureOutlined style="font-size: 40px; color: #bfbfbf" />
    </Skeleton.Node>
    <Skeleton :active="active" avatar :paragraph="{ rows: 3 }" style="flex: 1; min-width: 160px" />
  </div>
</template>
```

## 骨架元素 (element)

`Skeleton.Avatar` / `Skeleton.Button` / `Skeleton.Input` / `Skeleton.Image` 可独立组合，按钮统一切换 `active` 微光动画。

### element.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 element demo：五个骨架元素独立组合
import { Button, Flex, Skeleton } from '@apollo-design/ui';
import { ref } from 'vue';

const active = ref(true);
</script>

<template>
  <Flex vertical gap="middle">
    <Button size="small" style="width: 140px" @click="active = !active">
      {{ active ? '关闭微光动画' : '开启微光动画' }}
    </Button>
    <Flex gap="large" align="center" wrap>
      <Skeleton.Avatar :active="active" size="large" shape="circle" />
      <Skeleton.Avatar :active="active" size="large" shape="square" />
      <Skeleton.Button :active="active" size="large" />
      <Skeleton.Input :active="active" size="large" />
      <Skeleton.Image :active="active" />
    </Flex>
    <Skeleton.Button :active="active" block />
  </Flex>
</template>
```

---

# Slider

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/slider


# Slider 滑动输入条

滑动型输入器，展示当前值和可选范围。

## 何时使用

- 需要在有限范围内选择一个或多个数值时；
- 需要让用户直观感知「当前值在区间里的位置」时；
- 需要实时反馈（拖拽即改值）时。

## 引入

```ts
import { Slider } from '@apollo-design/ui';
```

## 代码演示



























## API

### Slider

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value（`v-model:value`） | 当前值：单把手是 `number`、`range` 时是 `number[]`；`null` 清空把手 | `number \| number[] \| null` | —— |
| defaultValue | 非受控初始值，支持 null 清空 | `number \| number[] \| null` | —— |
| min | 最小值 | `number` | `0` |
| max | 最大值 | `number` | `100` |
| step | 步长；`null` 表示只按 `marks` 取值 | `number \| null` | `1` |
| range | 双（多）把手；对象形态可开 `editable` / `draggableTrack` / `minCount` / `maxCount` | `boolean \| SliderRangeConfig` | `false` |
| count | 固定间隔数，实际把手数为 count + 1；存在时补齐/截断值。range.minCount/maxCount 是编辑上下限，职责不同 | `number` | —— |
| marks | 刻度标记，值可以是 `string` / 数字 / `{ label, style }` | `SliderMarks` | —— |
| dots | 是否显示刻度点（与 `step` 联用） | `boolean` | `false` |
| included | 是否显示已选轨道 | `boolean` | `true` |
| startPoint | 已选轨道的起点值 | `number` | `min` |
| track | `false` 时不渲染已选轨道 | `boolean` | `true` |
| disabled | 整体禁用，或**逐把手**禁用（数组） | `boolean \| boolean[]` | `false` |
| keyboard | 是否响应键盘 | `boolean` | `true` |
| autoFocus | 挂载后聚焦第一个未禁用的实际把手（含自定义槽节点） | `boolean` | `false` |
| reverse | 反向（横向自右向左；纵向时自上向下） | `boolean` | `false` |
| vertical | ⚠️ 已废弃，请用 `orientation` | `boolean` | `false` |
| orientation | 朝向 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| allowCross | 允许把手交叉 | `boolean` | `true` |
| pushable | 推挤间距：`true` = 一个 `step`；数字 = 该间距 | `boolean \| number` | `false` |
| formatter | tooltip 文案；`null` 表示永不显示 | `((value?: number) => VNodeChild) \| null` | 数字转字符串 |
| tooltip | tooltip 配置（`open` / `placement` / `getPopupContainer` …） | `SliderTooltipProps` | —— |
| tabIndex | 把手的 tabIndex（可传数组逐把手） | `number \| number[]` | `0` |
| ariaLabelForHandle | 把手的可访问名（可传数组） | `string \| string[]` | —— |
| ariaLabelledByForHandle | 把手的 `aria-labelledby`（可传数组） | `string \| string[]` | —— |
| ariaRequired | `aria-required` | `boolean` | —— |
| ariaValueTextFormatterForHandle | 把手的值文案（可传数组） | `(value: number) => string \| 数组` | —— |
| classNames | 语义化类名：`root` / `tracks` / `track` / `rail` / `handle` | `SliderSemanticClassNames` | —— |
| styles | 语义化样式：同上 5 槽 | `SliderSemanticStyles` | —— |
| dotStyle / activeDotStyle | 刻度点样式（可传函数按值求值） | `SliderDotStyle` | —— |
| handleStyle / trackStyle / railStyle | ⚠️ 已废弃，请用 `styles.handle` / `styles.track` / `styles.rail` | —— | —— |

### 事件

| 事件 | 说明 | 参数 |
| --- | --- | --- |
| `update:value` | 值变化（`v-model:value`） | `(value: number \| number[])` |
| `change` | 值变化（与 `update:value` 同时发出） | `(value: number \| number[])` |
| `beforeChange` | 本次有效交互的首个提议值；在 change 前发一次 | `(value: number \| number[])` |
| `changeComplete` | 交互结束的最后提议快照；受控拒绝时仍是提议值 | `(value: number \| number[])` |
| `focus` / `blur` | 把手获得 / 失去焦点 | `(event: FocusEvent, index: number)` |
| `keydown` / `keyup` | 把手原生键盘通知；keydown 在内部操作前发出，支持 preventDefault() | `(event: KeyboardEvent, index: number)` |

### 插槽

| 插槽 | 说明 | 参数 |
| --- | --- | --- |
| `handle` | 自定义实际把手；将 nodeProps 绑定到原生元素以保留 ARIA、事件及真实 ref | `{ index, prefixCls, value, dragging, draggingDelete, nodeProps, className, style }` |
| `activeHandle` | 自定义活动装饰锚点（无 role/键盘）；range 未锁定 open 且正悬停/聚焦/拖拽时，由默认 Tooltip 包装 | 同上 |

### 方法（ref）

| 方法 | 说明 |
| --- | --- |
| `focus()` | 聚焦第一个未禁用的实际把手（含自定义槽节点） |
| `blur()` | 若焦点在组件内则失焦 |

### 键盘

| 按键 | 行为 |
| --- | --- |
| ← / → | −1 / +1（反向或 RTL 时翻号） |
| ↑ / ↓ | +1 / −1（纵向 `reverse` 时翻号） |
| Home / End | 到 `min` / `max` |
| PageUp / PageDown | ±2 个「候选步」（候选集合 = `step` 网格 ∪ `marks`） |
| Backspace / Delete | 删除该节点（仅 `range.editable`，且受 `minCount` 限制） |

> ⚠️ **给把手的可访问名是使用方的责任**：`role="slider"` 需要一个可访问名，组件不会替你猜
> （`0..100` 的量在业务里可能叫音量 / 进度 / 评分）。不传 `ariaLabelForHandle` 时
> axe 会报 `aria-input-field-name` —— 与 antd 一致（见 `COMPATIBILITY.md` 的 U13）。


受控更新是提议，父级拒绝后 DOM/ARIA 保持当前接受值；撤控保留最后接受值，不保留未接受的拖拽草稿。输入会话的 beforeChange/changeComplete 保留提议快照，不读取可能已经回退的 DOM 值。没有变化、仅 keyup、输入法、preventDefault、touchcancel、配置失效和卸载不会产生伪完成通知。

class/style、data-*、title 及普通原生监听落根 div；style 支持 Vue 字符串、对象和数组。aria-* 与原生 tabindex 落实际把手，tabIndex/逐把手 ARIA props 优先，role/值域/当前值由组件保证。h() 原生键盘监听使用 onKeydown/onKeyup。

handle / activeHandle 使用公开 SliderHandleInfo（包括完整 HTMLAttributes 和真实 ref 的 nodeProps），活动 scope 的 index 是当前实际索引。默认槽与 Tooltip 包装在渲染时读取，自定义结构应保留唯一实际可操作把手并绑定 nodeProps。focus()/blur() 在挂载前后安全，模式/Tooltip 配置变化保留存活把手节点。

### Tooltip 与当前配置

tooltip.formatter 优先于顶层 formatter，null 关闭提示；二者均保留数值格式化职责。单把手和锁定 open=true 的范围逐个显示 Tooltip，默认范围使用唯一活动装饰锚点。位置/前缀/箭头/颜色/当前语义样式及显式容器按 Tooltip 自身契约消费，默认容器由 Tooltip 读取当前 Provider。

提示开关由 Slider 的真实焦点、hover、拖拽和 tooltip.open 拥有；不再声明无效的 tooltip.defaultOpen/trigger/onOpenChange/onUpdate:open，以及从未消费的内部 value/draggingDelete。draggingDelete 保留在真实 handle scope。

ConfigProvider.components.slider 的 className/style/classNames/styles 与当前方向、禁用响应替换及撤回。主题 token/算法与 theme.components.Slider 的 18 个 Token 投影到实际根变量，数字长度转为 px；原生根 style 的同名变量最后覆盖。自定义 prefixCls 需要对应静态 CSS，不会运行时生成选择器。

## 设计 Token

| Token | 默认值（light） | 说明 |
| --- | --- | --- |
| `controlSize` | `10` | 把手与轨道的基准尺寸（`controlHeightLG / 4`） |
| `railSize` | `4` | 底轨高度 |
| `handleSize` | `10` | 把手直径 |
| `handleSizeHover` | `12` | hover 时把手直径 |
| `dotSize` | `8` | 刻度点直径 |
| `handleLineWidth` | `2` | 把手描边宽度 |
| `handleLineWidthHover` | `2.5` | hover 时描边宽度 |
| `railBg` / `railHoverBg` | `rgba(0,0,0,0.04)` / `rgba(0,0,0,0.06)` | 底轨底色 / hover |
| `trackBg` / `trackHoverBg` | `#91caff` / `#69b1ff` | 已选轨道底色 / hover |
| `handleColor` / `handleActiveColor` | `#91caff` / `#1677ff` | 把手边框 / 激活 |
| `handleActiveOutlineColor` | `rgba(22,119,255,0.2)` | 把手激活外发光 |
| `handleColorDisabled` | `#bfbfbf` | 禁用把手 |
| `dotBorderColor` / `dotActiveBorderColor` | `#f0f0f0` / `#91caff` | 刻度点边框 / 选中 |
| `trackBgDisabled` | `rgba(0,0,0,0.04)` | 禁用时的已选轨道 |

主题切换请用当前 `ConfigProvider.theme`；静态 CSS 消费实际根投影的变量，不引入 CSS-in-JS 运行时。


## 基本 (basic)

最简单的用法：`v-model:value` 绑定值，`range` 切双把手，`disabled` 整体禁用。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd `basic.tsx`：单把手 + range，外加一个禁用开关（用本仓 Switch）。

import { Slider, Switch } from '@apollo-design/ui';
import { ref } from 'vue';

const disabled = ref(false);
const single = ref(30);
const rangeValue = ref<number[]>([20, 50]);
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Slider v-model:value="single" :disabled="disabled" />
    <Slider v-model:value="rangeValue" range :disabled="disabled" />
    <div>
      Disabled:
      <!-- ⚠️ 可切换控件必须自带可访问名（axe 的 button-name），旁边的文字不算 -->
      <Switch v-model:checked="disabled" size="small" aria-label="Disabled" />
    </div>
  </div>
</template>
```

## 带标记 (mark)

`marks` 的值可以是字符串、数字，或 `{ label, style }` 对象；刻度点与文字位置都按值定位。

### mark.vue

```vue
<script setup lang="ts">
// 对齐 antd `mark.tsx`：`marks` 的值可以是字符串 / 数字 / `{label, style}` 对象。
import { Slider } from '@apollo-design/ui';

const marks = {
  0: '0°C',
  26: '26°C',
  37: '37°C',
  100: { style: { color: '#f50' }, label: '100°C' },
};
</script>

<template>
  <div style="padding-inline: 16px">
    <Slider :default-value="37" :marks="marks" />
  </div>
</template>
```

## 垂直 (vertical)

`orientation="vertical"` 纵向滑动（旧写法 `vertical` 仍可用但会在开发期告警）。

### vertical.vue

```vue
<script setup lang="ts">
// 对齐 antd `vertical.tsx`：`orientation="vertical"`（旧的 `vertical` 仍可用但已废弃）。
import { Slider } from '@apollo-design/ui';

const marks = { 0: '0°C', 26: '26°C', 37: '37°C', 100: '100°C' };
</script>

<template>
  <div style="height: 300px; display: flex; justify-content: center">
    <Slider orientation="vertical" :default-value="37" :marks="marks" />
  </div>
</template>
```

## 反向 (reverse)

`reverse` 让轨道反向；RTL 页面下会再取反一次（与 antd 一致）。

### reverse.vue

```vue
<script setup lang="ts">
// 对齐 antd `reverse.tsx`：`reverse` 让横向滑块反向（RTL 页面上会再取反一次）。
import { Slider } from '@apollo-design/ui';
</script>

<template>
  <Slider reverse :default-value="40" :marks="{ 0: '0', 50: '50', 100: '100' }" />
</template>
```

## 禁用单个把手 (disabled-handle)

`disabled` 传数组时逐把手生效：禁用的把手不可聚焦、不可拖、不响应键盘。

### disabled-handle.vue

```vue
<script setup lang="ts">
// 对齐 antd `disabled-handle.tsx`：`disabled` 收**数组**时逐把手生效（禁用的把手不可聚焦、不可拖）。
import { Slider } from '@apollo-design/ui';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Slider :default-value="[20, 60]" range :disabled="[true, false]" />
    <Slider :default-value="[10, 50, 90]" range :disabled="[false, true, false]" />
  </div>
</template>
```

## 可编辑节点 (editable)

`range.editable` 下可点击插入节点、Backspace/Delete 删除节点、拖拽删除；`minCount` / `maxCount` 限制数量。

### editable.vue

```vue
<script setup lang="ts">
// 对齐 antd `editable.tsx`：`range.editable` 下可用键盘 Backspace/Delete 删节点、拖拽删除，
// 点击轨道可插入新节点（`minCount` / `maxCount` 限制把手数量）。
import { Slider } from '@apollo-design/ui';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Slider :default-value="[10, 50, 90]" :range="{ editable: true }" />
    <Slider :default-value="[10, 50]" :range="{ editable: true, minCount: 2, maxCount: 4 }" />
  </div>
</template>
```

## 可拖拽轨道 (draggable-track)

`range.draggableTrack` 拖动整条已选轨道（与 `editable` 互斥；`step: null` 时自动关闭）。

### draggable-track.vue

```vue
<script setup lang="ts">
// 对齐 antd `draggableTrack.tsx`：`range.draggableTrack` 可拖整条已选轨道
// （⚠️ 与 `editable` 互斥；`step: null` 时被自动关闭并告警）。
import { Slider } from '@apollo-design/ui';
</script>

<template>
  <Slider :default-value="[20, 60]" :range="{ draggableTrack: true }" />
</template>
```

## 事件 (event)

`beforeChange` → `change`/`update:value` → `changeComplete` 三条事件链；单把手载荷是数字、range 是数组。

### event.vue

```vue
<script setup lang="ts">
// 对齐 antd `event.tsx`：三条事件链 —— beforeChange（开始）→ change（每次变化）→
// changeComplete（拖拽/键盘结束）。⚠️ `change` 的载荷：单把手是数字、range 是数组。
import { Slider, type SliderValue } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<SliderValue>([20, 60]);
const log = ref<string[]>([]);
const push = (tag: string, payload: SliderValue): void => {
  log.value = [`${tag}: ${JSON.stringify(payload)}`, ...log.value].slice(0, 5);
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Slider
      v-model:value="value"
      range
      @before-change="(v: SliderValue) => push('beforeChange', v)"
      @change="(v: SliderValue) => push('change', v)"
      @change-complete="(v: SliderValue) => push('changeComplete', v)"
    />
    <pre style="margin: 0">{{ log.join('\n') }}</pre>
  </div>
</template>
```

## 提示格式化 (tip-formatter)

`formatter` 定制 tooltip 文案；传 `null` 则永不显示。

### tip-formatter.vue

```vue
<script setup lang="ts">
// 对齐 antd `tipFormatter.tsx`：`formatter` 定制提示文案；传 `null` 则**永不显示** tooltip。
import { Slider } from '@apollo-design/ui';

const formatter = (value?: number): string => `${value}%`;
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Slider :default-value="30" :formatter="formatter" />
    <Slider :default-value="30" :formatter="null" />
  </div>
</template>
```

## 常显提示 (show-tooltip)

`tooltip.open` 受控开合（`false` 锁定关闭）。

### show-tooltip.vue

```vue
<script setup lang="ts">
// 对齐 antd `show-tooltip.tsx`：`tooltip.open` 受控开合（`false` ⇒ 永不显示）。
import { Slider } from '@apollo-design/ui';
</script>

<template>
  <Slider :default-value="30" :tooltip="{ open: true }" />
</template>
```

## 自定义把手图标 (icon-slider)

`#handle` 作用域插槽自定义把手（槽参数给出可用的 `nodeProps` / `className` / `style`）。

### icon-slider.vue

```vue
<script setup lang="ts">
// 对齐 antd `icon-slider.tsx`：`#handle` 槽自定义把手。槽参数给出 `nodeProps` / `className` /
// `style`（与 rc 的 `handleRender(node, info)` 同构 —— 可替换、也可在里面再包一层）。
import { FrownOutlined, SmileOutlined } from '@apollo-design/icons';
import { Slider } from '@apollo-design/ui';
import { computed, h, ref } from 'vue';

const value = ref(30);
const icon = computed(() => (value.value < 50 ? h(FrownOutlined) : h(SmileOutlined)));
</script>

<template>
  <Slider v-model:value="value">
    <template #handle="{ nodeProps, className, style }">
      <div v-bind="nodeProps" :class="className" :style="style">
        <component :is="icon" />
      </div>
    </template>
  </Slider>
</template>
```

## 多把手 (multiple)

`count` 决定把手数量：不足的用最后一个值补齐。

### multiple.vue

```vue
<script setup lang="ts">
// 对齐 antd 的「多把手」用法：`count` 决定把手数量（`range` 开启后不足的用最后一个值补齐）。
import { Slider } from '@apollo-design/ui';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Slider :default-value="[10, 30, 60]" :count="3" range />
    <Slider :default-value="30" :count="5" range />
  </div>
</template>
```

## 与数字输入框联动 (input-number)

与 `InputNumber` 联动，两者共用同一个值。

### input-number.vue

```vue
<script setup lang="ts">
// 对齐 antd `slider-with-input-number.tsx`：与 InputNumber 联动（两者共用同一个值）。

import { InputNumber, Slider } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref(30);
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px">
    <Slider v-model:value="value" style="flex: 1" />
    <!-- ⚠️ 数值输入框必须自带可访问名（axe 的 label），Slider 的把手同理见 README/U13 -->
    <InputNumber v-model:value="value" aria-label="Value" />
  </div>
</template>
```

## 组件 Token (component-token)

通过当前 `ConfigProvider.theme.components.Slider` 配置轨道尺寸、把手尺寸与主色，数值长度在实际根转换为 px 变量。原生根 style 的同名 CSS 变量仍可覆盖。

### component-token.vue

```vue
<script setup lang="ts">
// 当前子树的 Slider Token 通过 ConfigProvider 进入实际根变量。
import { ConfigProvider, Slider } from '@apollo-design/ui';

const marks = { 0: '0°C', 26: '26°C', 37: '37°C', 100: '100°C' };
</script>

<template>
  <ConfigProvider :theme="{ components: { Slider: {
    controlSize: 14, railSize: 6, handleSize: 14, handleSizeHover: 18,
    railBg: '#f0f5ff', railHoverBg: '#e6f4ff', trackBg: '#722ed1', trackHoverBg: '#9254de',
    handleColor: '#722ed1', handleActiveColor: '#531dab', dotBorderColor: '#d3adf7', dotActiveBorderColor: '#722ed1',
  } } }">
    <div style="display: flex; flex-direction: column; gap: 32px; max-width: 480px">
      <Slider :default-value="30" :aria-label-for-handle="'Customized slider'" />
      <Slider
        range
        :default-value="[20, 60]"
        :marks="marks"
        :aria-label-for-handle="['Lower bound', 'Upper bound']"
      />
    </div>
  </ConfigProvider>
</template>
```

## 语义化样式 (style-class)

根节点使用原生 `class`；轨道与把手通过 `classNames` 加类、通过 `styles` 写行内样式。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo：根节点用原生 class，内部槽位用 classNames / styles。
import { Slider } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref(40);
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; max-width: 480px">
    <Slider
      class="demo-slider-style-root"
      :class-names="{
        rail: 'demo-slider-style-rail',
        track: 'demo-slider-style-track',
        handle: 'demo-slider-style-handle',
      }"
      :styles="{ track: { backgroundImage: 'linear-gradient(90deg, #1677ff 0%, #52c41a 100%)' } }"
      v-model:value="value"
      :aria-label-for-handle="'Styled slider'"
    />
    <div>当前值：{{ value }}</div>
  </div>
</template>

<style>
.demo-slider-style-root .demo-slider-style-rail {
  background: #fffbe6;
  border: 1px dashed #faad14;
}

.demo-slider-style-root .demo-slider-style-track {
  border-radius: 999px;
}

.demo-slider-style-root .demo-slider-style-handle::after {
  box-shadow: 0 0 0 3px #52c41a;
}
</style>
```

---

# Space

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/space


设置内容间距；用 `SpaceCompact` 连接相邻控件，用 `SpaceAddon` 插入自定义单元格。

## 代码演示

[`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/space/demo) 中的 15 个示例使用真实 Apollo 控件：基础、垂直、尺寸、对齐、换行、分隔符、紧凑布局、按钮组、垂直按钮组、嵌套紧凑、紧凑调试、空内容、换行间距、语义样式与 Alias 主题。

## API

### Space

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| prefixCls | 完整 DOM 类名前缀 | `string` | ConfigProvider 前缀 + `-space` |
| size | 间距，数组按 `[水平, 垂直]` | `SpaceSize \| [SpaceSize, SpaceSize]` | 当前 `components.space.size`，再回落到 `'small'` |
| orientation | 排列方向，优先级最高 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| vertical | 显式 false 也优先于旧 direction | `boolean` | — |
| align | 水平默认 center，垂直未传不添加对齐 | `'start' \| 'end' \| 'center' \| 'baseline'` | 水平 `'center'` |
| separator | 完整 Vue 内容数据，数字 0 会渲染 | `VNodeChild` | — |
| wrap | 启用 flex 换行；纵向换行需限制容器高度 | `boolean` | `false` |
| classNames | root/item/separator 类名，对象或接收当前 `{ props }` 的函数 | `SpaceSemanticValue<SpaceSemanticClassNames>` | — |
| styles | root/item/separator 样式，对象或接收当前 `{ props }` 的函数 | `SpaceSemanticValue<SpaceSemanticStyles>` | — |
| ~~direction~~ | 已废弃，使用 orientation | `'horizontal' \| 'vertical'` | — |
| ~~split~~ | 已废弃，使用 separator 数据或 #separator | `VNodeChild` | — |

`SpaceSize = 'small' | 'medium' | 'middle' | 'large' | number`。预设间距来自 `paddingXS` / `padding` / `paddingLG` Alias，数字按 px 设置双向 gap；0 为有效零间距，不回落到默认值。NaN 不设置 gap。

| 插槽 | 说明 |
| --- | --- |
| default | 当前内容，每个非空子节点有一个 `-item` 宿主 |
| separator | 优先于 separator 和 split 数据；存在但留空时隐藏分隔符 |

插槽在渲染时读取，支持条件插槽的新增、替换和移除。分隔符数据优先级为 `#separator` → `separator`（非 undefined）→ `split`。null、false、空字符串和注释为空内容；数字 0 是内容。只有两个有内容项之间才渲染分隔宿主。

Fragment/数组会展平，保留 keyed Fragment 的 key 作用域。合法字符串、数字和 Symbol key 以及外观更新均不改变业务子组件身份；未显式 key 的节点按位置保持身份。没有默认槽/零个子节点时不渲染根；非空列表中的空占位可保留根，但不产生 item 宿主。

### SpaceCompact

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| prefixCls | 完整 DOM 类名前缀 | `string` | ConfigProvider 前缀 + `-space-compact` |
| size | 传播给子控件的尺寸 | `SizeType` | 当前 ConfigProvider.componentSize |
| orientation | 排列方向 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| vertical | 显式布尔方向，低于 orientation | `boolean` | — |
| block | 撑满父元素宽度 | `boolean` | `false` |
| ~~direction~~ | 已废弃，使用 orientation | `'horizontal' \| 'vertical'` | — |

默认槽为真实紧凑控件；不增加控件 DOM 包装。null、布尔、注释、空文本不占首尾位置；数字 0 保留。嵌套组的首尾边界与外层合取。子控件以自己的前缀消费 `compactSize`、`compactDirection`、`isFirstItem`、`isLastItem`。对于支持尺寸的控件，显式 size 优先于当前 compactSize，再回落到 Provider 尺寸。

`useCompactItemContext(prefixCls, direction)` 返回三个 ComputedRef：`compactSize`、`compactDirection`、`compactItemClassnames`。水平类名为 `-compact-item` / `-compact-first-item` / `-compact-last-item`，纵向为 `-compact-vertical-*`，RTL 添加对应 item-rtl。`NoCompactStyle` 用 null 隔离当前子树，邻近实例不受影响；被隔离控件回落到自身/Provider 配置。

### SpaceAddon

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| prefixCls | 完整 DOM 类名前缀 | `string` | ConfigProvider 前缀 + `-space-addon` |
| variant | 单元格外观 | `'outlined' \| 'filled' \| 'borderless' \| 'underlined'` | `'outlined'` |
| disabled | 单元格的装饰禁用态，子控件仍自行控制 disabled | `boolean` | `false` |
| status | 校验外观 | `'error' \| 'warning' \| 'success' \| 'validating' \| ''` | — |

默认槽接收完整 Vue 内容。Addon 使用当前 Compact 尺寸和首尾边界；outlined/filled 的横向、纵向、RTL 连接保留外侧圆角，单项保留四角。underlined 为透明背景、零圆角的单独底线，使用当前 lineWidth/lineType；borderless 无边框。error/warning 文字由现有 colorErrorText/colorWarningText 与 colorText 等量混合派生，outlined 边框及 underlined 底线保留状态色。disabled 文字色优先于状态文字色，不移除底线或状态边框色；filled + disabled 恢复禁用背景。success/validating 保留状态类，不额外改变颜色。

### 原生 attrs、ref 与配置

三个组件的 `class`、`style`、原生监听器、data-*、ARIA 等 attrs 落在根 div；原生 style 支持 Vue 对象、字符串和数组。没有业务 emits 或 v-model，也不添加列表/表单语义。交互语义由实际按钮/输入控件承担。

三个 ref 仅开放 `nativeElement: HTMLDivElement | null`。挂载前及 Space/Compact 无内容时为 null；Addon 始终有根。

Space 配置为 `ConfigProvider :components="{ space: { size, className, style, classNames, styles } }"`。配置替换和移除即时生效。类名拼接；样式按 Provider semantic → Provider root style → 本地 semantic → 原生 attrs 合并。语义函数收到当前合并的 size/orientation/align，不是 setup 快照。

### 主题与导出

Space / Compact / Addon 当前没有 ComponentToken，`prepareSpaceComponentToken` 返回 `{}`。使用已有 Alias token 调整间距、字体、线宽、圆角与 Addon 颜色；不新增 `theme.components.Space` 字段。当前主题 Alias 同时支持 ConfigProvider、ThemeProvider、嵌套作用域及 SSR；根原生 style 中的变量覆盖优先。

```ts
import { Space, SpaceCompact, SpaceAddon } from '@apollo-design/ui';
import '@apollo-design/theme/tokens.css';
import '@apollo-design/ui/space/style.css';
```

真实 Button/Input/Select 等控件还需各自 CSS，或使用汇总 `@apollo-design/ui/style.css`。

保留 `Space.Compact` / `Space.Addon` 静态别名，以及 `ASpace` / `ASpaceCompact` / `ASpaceAddon` 各自安装名。公开类型包括 SpaceProps/Ref/Size/Align/Slot/Config、SpaceCompactProps/Ref/ItemContextType、SpaceAddonProps/Ref 和既有语义类型。公开上下文和工具导出保持不变。

`prefixCls` 只改变 DOM 命名，不自动生成任意前缀 CSS。`genSpaceStyle('brand')` 生成 `.brand-space`、`.brand-space-compact`、`.brand-space-addon` 的静态 CSS；全局 Provider 前缀应与预先生成的 CSS 对应。默认产物为 apollo 前缀。

本轮行为调整及旧写法见 [迁移说明](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/space-contracts.md)。


## 基础用法 (base)

使用真实 Button 和默认插槽内容设置间距。

Use real Buttons and default slot content with consistent spacing.

### base.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
</script>
<template>
  <Space wrap>Space <Button type="primary">Save</Button><Button>Upload</Button><Button type="text">Confirm</Button></Space>
</template>
```

## 垂直间距 (vertical)

垂直排列真实 Card；使用 `style="display: flex"` 撑满容器。

Stack real Cards vertically and stretch the layout with native style.

### vertical.vue

```vue
<script setup lang="ts">
import { Card, Space } from '@apollo-design/ui';
</script>
<template>
  <Space orientation="vertical" size="medium" style="display: flex">
    <Card v-for="i in 3" :key="i" title="Card" size="small"><p>Card content</p><p>Card content</p></Card>
  </Space>
</template>
```

## 间距尺寸 (size)

切换预设与数字间距；自定义 `0` 保持零间距。

Switch presets and numeric gaps; zero remains a zero gap.

### size.vue

```vue
<script setup lang="ts">
import { Button, Select, Slider, Space, type SpaceSize } from '@apollo-design/ui';
import { ref } from 'vue';

type Choice = 'small' | 'medium' | 'large' | 'customize';
const size = ref<Choice>('small');
const customSize = ref(0);
const spaceSize = (): SpaceSize => (size.value === 'customize' ? customSize.value : size.value);
</script>
<template>
  <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px">Spacing <Select v-model:value="size" aria-label="Space size" style="width: 140px" :options="['small', 'medium', 'large', 'customize'].map(value => ({ value, label: value }))" /></div>
  <div v-if="size === 'customize'" style="margin-top: 12px">Custom gap: {{ customSize }}px <Slider v-model:value="customSize" :min="0" :max="100" aria-label="Custom size" /></div>
  <div style="margin-top: 16px"><Space :size="spaceSize()" wrap><Button type="primary">Primary</Button><Button>Default</Button><Button type="dashed">Dashed</Button><Button type="text">Text</Button></Space></div>
</template>
```

## 对齐 (align)

比较四种对齐方式，内容包含真实 Button 与不同高度的业务块。

Compare all four alignments with real Buttons and content of different heights.

### align.vue

```vue
<script setup lang="ts">
import { Button, Flex, Space, type SpaceAlign } from '@apollo-design/ui';

const alignments: SpaceAlign[] = ['center', 'start', 'end', 'baseline'];
</script>
<template>
  <Flex wrap="wrap" align="start">
    <Space v-for="align in alignments" :key="align" :align="align" class="alignment-box">
      {{ align }}<Button type="primary">Primary</Button><span class="tall-block">Block</span>
    </Space>
  </Flex>
</template>
<style scoped>
.alignment-box { margin: 4px; padding: 4px; border: 1px solid var(--apollo-color-primary); }
.tall-block { display: inline-block; padding: 24px 16px; color: var(--apollo-color-text); background: var(--apollo-color-fill-secondary); }
</style>
```

## 自动换行 (wrap)

实际按钮换行，水平间距 8px、行距 16px。

Wrap real Buttons with an 8px horizontal and 16px vertical gap.

### wrap.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
</script>
<template><Space :size="[8, 16]" wrap><Button v-for="i in 20" :key="i">Button {{ i }}</Button></Space></template>
```

## 分隔符 (separator)

通过 `#separator` 使用 Divider；分隔符插槽优先于 separator/split 数据，故意留空可以隐藏。

Use Divider through #separator; a present slot takes priority over separator/split data, including intentional empty content.

### separator.vue

```vue
<script setup lang="ts">
import { Divider, Space } from '@apollo-design/ui';
</script>
<template>
  <Space><template #separator><Divider orientation="vertical" /></template><a href="#first">First link</a><a href="#second">Second link</a><a href="#third">Third link</a></Space>
</template>
<style scoped>a { color: inherit; text-decoration: underline; }</style>
```

## 紧凑布局 (compact)

十一组真实 Input、Select、InputNumber、DatePicker、Button 和 Addon。尺寸与紧凑类名通过响应式上下文传播，支持实际输入、选择与键盘焦点。

Site URL 行保留 `size="small"` 的密集排版，同时给输入框和按钮显式设置 `min-height: 24px`，为相邻可点击目标保留至少 24px 的高度并保持连接等高；紧凑主题下字体仍为 12px。

Eleven groups of real controls receive current sizes and compact edge classes through context. Inputs, selections and keyboard focus remain functional.

The Site URL row keeps `size="small"` for dense layouts and explicitly sets `min-height: 24px` on both controls. Adjacent interactive targets retain at least 24px of height and stay aligned, while compact themes keep the 12px font.

### compact.vue

```vue
<script setup lang="ts">
import {
  Button,
  DatePicker,
  Input,
  InputNumber,
  Select,
  Space,
  SpaceAddon,
  SpaceCompact,
} from '@apollo-design/ui';

const provinces = [
  { value: 'zhejiang', label: 'Zhejiang' },
  { value: 'jiangsu', label: 'Jiangsu' },
];
const actions = [
  { value: 'signup', label: 'Sign Up' },
  { value: 'signin', label: 'Sign In' },
];
</script>
<template>
  <div style="max-width: 100%; overflow-x: auto; padding: 2px" tabindex="0" aria-label="Compact control examples">
  <Space orientation="vertical" style="display: flex">
    <SpaceCompact block><Input aria-label="Area code" default-value="0571" style="width: 20%" /><Input aria-label="Phone" default-value="26888888" style="width: 80%" /></SpaceCompact>
    <SpaceCompact block size="small"><Input aria-label="Site URL" default-value="https://example.com" style="min-height: 24px" /><Button type="primary" style="min-height: 24px">Submit</Button></SpaceCompact>
    <SpaceCompact block><Input aria-label="Git URL" default-value="git@example.com:project/repository.git" /><Button>Copy</Button></SpaceCompact>
    <SpaceCompact block><Select aria-label="Province" :options="provinces" default-value="zhejiang" style="width: 140px" /><Input aria-label="District" default-value="Xihu District, Hangzhou" /></SpaceCompact>
    <SpaceCompact block><Select aria-label="Multiple provinces" :options="provinces" mode="multiple" :default-value="['zhejiang']" style="width: 50%" /><Input aria-label="Second district" default-value="Xihu District, Hangzhou" style="width: 50%" /></SpaceCompact>
    <SpaceCompact block><Select aria-label="Option" :options="provinces" default-value="zhejiang" style="width: 140px" /><Input aria-label="Input content" placeholder="Input content" /><InputNumber aria-label="Quantity" :default-value="12" /></SpaceCompact>
    <SpaceCompact block><Input aria-label="Date prefix" placeholder="Booking reference" /><DatePicker aria-label="Booking date" /></SpaceCompact>
    <SpaceCompact block><Select aria-label="Account action" :options="actions" default-value="signup" style="width: 140px" /><Input aria-label="Email" placeholder="Email" /></SpaceCompact>
    <SpaceCompact block><Select aria-label="Range rule" :options="[{ value: 'between', label: 'Between' }, { value: 'except', label: 'Except' }]" default-value="between" style="width: 130px" /><InputNumber aria-label="Minimum" placeholder="Minimum" /><SpaceAddon>~</SpaceAddon><InputNumber aria-label="Maximum" placeholder="Maximum" /></SpaceCompact>
    <SpaceCompact block><Input aria-label="First amount" placeholder="First amount" /><SpaceAddon>$</SpaceAddon><Input aria-label="Second amount" placeholder="Second amount" /><Input aria-label="Third amount" placeholder="Third amount" /><SpaceAddon>$</SpaceAddon></SpaceCompact>
    <SpaceCompact block><Button type="primary">Button</Button><Input aria-label="Amount with unit" placeholder="Input here" /><SpaceAddon>$</SpaceAddon></SpaceCompact>
  </Space>
  </div>
</template>
```

## 紧凑按钮组 (compact-buttons)

真实按钮的紧凑边框、主按钮与禁用态。

Compact borders, primary actions and disabled states use real Buttons.

### compact-buttons.vue

```vue
<script setup lang="ts">
import { Button, Space, SpaceCompact } from '@apollo-design/ui';

const actions = ['Like', 'Comment', 'Star', 'Heart', 'Share', 'Download', 'More'];
</script>
<template>
  <div style="max-width: 100%; overflow-x: auto; padding: 2px" tabindex="0" aria-label="Compact control examples">
  <Space orientation="vertical" style="display: flex">
    <SpaceCompact block><Button v-for="action in actions" :key="action">{{ action }}</Button></SpaceCompact>
    <SpaceCompact block><Button v-for="i in 6" :key="i" type="primary" :disabled="i === 5">Button {{ i }}</Button></SpaceCompact>
    <SpaceCompact block><Button v-for="i in 5" :key="i" :disabled="i === 4">Button {{ i }}</Button><Button type="primary">More</Button></SpaceCompact>
  </Space>
  </div>
</template>
```

## 垂直紧凑按钮组 (compact-button-vertical)

纵向紧凑按钮支持默认、虚线、主按钮和 outlined 外观。

Vertical compact Buttons with default, dashed, primary and outlined appearances.

### compact-button-vertical.vue

```vue
<script setup lang="ts">
import { Button, Space, SpaceCompact } from '@apollo-design/ui';
</script>
<template>
  <Space align="start" wrap>
    <SpaceCompact orientation="vertical"><Button v-for="i in 3" :key="i">Button {{ i }}</Button></SpaceCompact>
    <SpaceCompact orientation="vertical"><Button v-for="i in 3" :key="i" type="dashed">Button {{ i }}</Button></SpaceCompact>
    <SpaceCompact orientation="vertical"><Button v-for="i in 3" :key="i" type="primary">Button {{ i }}</Button></SpaceCompact>
    <SpaceCompact orientation="vertical"><Button v-for="i in 3" :key="i" variant="outlined">Button {{ i }}</Button></SpaceCompact>
  </Space>
</template>
```

## 嵌套紧凑布局 (compact-nested)

嵌套真实输入、Search、数字、Select 和 TimePicker，首尾边界沿 Compact 层级合取。

Nested real inputs, Search, number controls, Select and TimePicker preserve first/last boundaries across Compact levels.

### compact-nested.vue

```vue
<script setup lang="ts">
import {
  Button,
  Input,
  InputNumber,
  InputSearch,
  Select,
  Space,
  SpaceCompact,
  TimePicker,
} from '@apollo-design/ui';

const options = [
  { value: 'opt1', label: 'Option 1' },
  { value: 'opt2', label: 'Option 2' },
];
</script>
<template>
  <div style="max-width: 100%; overflow-x: auto; padding: 2px" tabindex="0" aria-label="Compact control examples">
  <Space orientation="vertical" style="display: flex">
    <SpaceCompact block>
      <SpaceCompact><SpaceCompact><Input aria-label="Nested query" placeholder="Typing…" style="width: 90px" /><Button type="primary">Search</Button></SpaceCompact><SpaceCompact><InputNumber aria-label="Nested number" :default-value="12" /><Select aria-label="Nested option" :options="options" default-value="opt1" style="width: 110px" /></SpaceCompact></SpaceCompact>
      <Button>Separator</Button>
      <SpaceCompact><SpaceCompact><InputSearch aria-label="Nested search" placeholder="Search" style="width: 170px" /></SpaceCompact><SpaceCompact><Input aria-label="Nested site" default-value="mysite" style="width: 110px" /><Button>Copy</Button></SpaceCompact></SpaceCompact>
    </SpaceCompact>
    <SpaceCompact block><SpaceCompact><TimePicker aria-label="Nested time" /><Button type="primary">Submit</Button></SpaceCompact><Button>~</Button><Button>~</Button><SpaceCompact><Select aria-label="Nested address" :options="options" default-value="opt1" style="width: 130px" /><Button type="primary">Submit</Button></SpaceCompact></SpaceCompact>
    <SpaceCompact><Button v-for="i in 4" :key="i" type="primary">Button {{ i }}</Button></SpaceCompact>
  </Space>
  </div>
</template>
```

## 紧凑布局调试 (compact-debug)

实际前后标签、计数输入、单项控件，以及纵向与单项 Addon。三种尺寸的 underlined 展示 normal/error/warning/disabled 底线，borderless 对照保持无边框。disabled Addon 只提供装饰外观；示例中的操作 Button 另行显式传入 disabled，表示真实不可用的操作。

Real prefix/suffix cells, counted inputs, single controls, vertical and single Addons. Underlined cells show normal/error/warning/disabled bottom borders in three sizes; borderless cells retain no border. Addon disabled is decorative; each unavailable action Button explicitly receives its own disabled prop.

### compact-debug.vue

```vue
<script setup lang="ts">
import {
  Button,
  Cascader,
  DatePicker,
  Input,
  InputNumber,
  Select,
  Space,
  SpaceAddon,
  SpaceCompact,
} from '@apollo-design/ui';

const options = [
  { value: 'signup', label: 'Sign Up' },
  { value: 'signin', label: 'Sign In' },
];
const addonSizes = ['small', 'middle', 'large'] as const;
</script>
<template>
  <div style="max-width: 100%; overflow-x: auto; padding: 2px" tabindex="0" aria-label="Compact control examples">
  <Space orientation="vertical" style="display: flex">
    <SpaceCompact><Button>Default</Button><Button danger>Danger</Button><Button type="dashed">Dashed</Button><Button type="text">Text</Button><Button type="link">Link</Button><Button disabled>Disabled</Button></SpaceCompact>
    <SpaceCompact block><SpaceAddon>Prefix</SpaceAddon><Input aria-label="Site with prefix" default-value="mysite" /><Button type="primary">Submit</Button></SpaceCompact>
    <SpaceCompact block><Input aria-label="Prefix field" placeholder="Prefix" /><Input aria-label="Site field" default-value="mysite" /><Button>Copy</Button></SpaceCompact>
    <SpaceCompact block><Input aria-label="Search A" placeholder="Search" /><Input aria-label="Search B" placeholder="Search" /><Button>Copy</Button></SpaceCompact>
    <SpaceCompact block><Input aria-label="Suffix field" default-value="mysite" /><Button type="primary">Submit</Button><Input aria-label="Suffix tail" placeholder="Suffix" /></SpaceCompact>
    <SpaceCompact block><Input aria-label="Counted field" default-value="mysite" show-count /><Button type="primary">Submit</Button><Input aria-label="Counted tail" default-value="mysite" show-count /><Input aria-label="Counted tail two" default-value="mysite" /></SpaceCompact>
    <SpaceCompact><InputNumber aria-label="Number with unit" :default-value="100" /><SpaceAddon>$</SpaceAddon></SpaceCompact>
    <SpaceCompact><Select aria-label="Single account action" :options="options" default-value="signup" style="width: 140px" /></SpaceCompact>
    <SpaceCompact><DatePicker aria-label="Single date" /></SpaceCompact>
    <SpaceCompact><InputNumber aria-label="Single number" :default-value="12" /></SpaceCompact>
    <SpaceCompact><Cascader aria-label="Single address" :options="[{ value: 'zhejiang', label: 'Zhejiang', children: [{ value: 'hangzhou', label: 'Hangzhou' }] }]" /></SpaceCompact>
    <SpaceCompact orientation="vertical" size="small"><Button>Vertical single button</Button></SpaceCompact>
    <SpaceCompact orientation="vertical"><SpaceAddon>Vertical first</SpaceAddon><SpaceAddon>Vertical middle</SpaceAddon><SpaceAddon>Vertical last</SpaceAddon></SpaceCompact>
    <SpaceCompact><SpaceAddon>Single addon</SpaceAddon></SpaceCompact>
    <SpaceCompact v-for="size in addonSizes" :key="size" :size="size"><SpaceAddon variant="underlined">Underlined {{ size }}</SpaceAddon><SpaceAddon variant="underlined" status="error">Error</SpaceAddon><SpaceAddon variant="underlined" status="warning">Warning</SpaceAddon><SpaceAddon variant="underlined" disabled><Button type="text" disabled>Disabled</Button></SpaceAddon></SpaceCompact>
    <SpaceCompact><SpaceAddon variant="borderless">Borderless</SpaceAddon><SpaceAddon variant="borderless" status="error">Error</SpaceAddon><SpaceAddon variant="borderless" status="warning">Warning</SpaceAddon><SpaceAddon variant="borderless" disabled><Button type="text" disabled>Disabled</Button></SpaceAddon></SpaceCompact>
  </Space>
  </div>
</template>
```

## 假值子节点 (debug)

数字 `0` 是内容；null、false、undefined 不产生内容包装。

Zero is content; null, false and undefined do not create content wrappers.

### debug.vue

```vue
<script setup lang="ts">
import { Button, Space } from '@apollo-design/ui';
import { h, type VNodeChild } from 'vue';

const items: VNodeChild[] = [
  'Button',
  h(Button, null, () => 'Button'),
  'Button',
  h(Button, null, () => 'Delete'),
  h(Button, { disabled: true }, () => 'Delete'),
  null,
  false,
  0,
  'Button',
  null,
  undefined,
];
const Demo = () => h(Space, { wrap: true }, { default: () => items });
</script>
<template><component :is="Demo" /></template>
```

## 换行时的行距 (gap-in-line)

用临界容器宽度切换换行，核对水平 gap 与行距。

Toggle a threshold container width to inspect column and row gaps.

### gap-in-line.vue

```vue
<script setup lang="ts">
import { Checkbox, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const singleCol = ref(false);
</script>
<template>
  <Checkbox v-model:checked="singleCol">Single column</Checkbox>
  <div style="max-width: 100%; overflow: auto; margin-top: 12px"><Space :style="{ width: singleCol ? '307px' : '310px' }" :size="[8, 8]" wrap><div v-for="i in 4" :key="i" class="gap-box">{{ i }}</div></Space></div>
</template>
<style scoped>.gap-box { width: 150px; height: 100px; display: grid; place-items: center; color: var(--apollo-color-text); background: var(--apollo-color-fill-secondary); }</style>
```

## 自定义语义结构的样式和类 (style-class)

对象与函数式语义样式采用当前合并后的 props；主题变量随所属作用域变化。

Object and function semantic styles receive current merged props and use scoped theme variables.

### style-class.vue

```vue
<script setup lang="ts">
import { Button, Space, type SpaceProps } from '@apollo-design/ui';

const classNames: SpaceProps['classNames'] = {
  root: 'demo-space-root',
  item: 'demo-space-item',
  separator: 'demo-space-separator',
};
const styles: SpaceProps['styles'] = {
  root: { border: '2px dashed var(--apollo-color-border)', padding: '8px', marginBottom: '10px' },
  item: { background: 'var(--apollo-color-fill-secondary)', padding: '4px' },
  separator: { color: 'var(--apollo-color-primary)', fontWeight: 'bold' },
};
const classNamesFn: SpaceProps['classNames'] = ({ props }) => ({
  root: `demo-space-${props.orientation}`,
});
const stylesFn: SpaceProps['styles'] = ({ props }) => ({
  root: {
    background:
      props.size === 'large'
        ? 'var(--apollo-color-primary-bg)'
        : 'var(--apollo-color-fill-secondary)',
    padding: '8px',
  },
});
</script>
<template>
  <div style="display: grid; gap: 16px"><Space wrap :styles="styles" :class-names="classNames" separator="•"><Button v-for="i in 3" :key="i">Styled {{ i }}</Button></Space><Space wrap size="large" :styles="stylesFn" :class-names="classNamesFn"><Button v-for="i in 3" :key="i">Large space {{ i }}</Button></Space></div>
</template>
```

## 组件 Token (component-token)

Space / Compact / Addon 当前没有组件 Token。使用已有 Alias Token 在 ConfigProvider 中局部调整预设 gap 与 Addon 颜色；不虚构 theme.components.Space 字段。

Space, Compact and Addon have no component tokens. Existing Alias tokens in ConfigProvider control local preset gaps and Addon paint.

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, Space, SpaceAddon, SpaceCompact } from '@apollo-design/ui';
</script>
<template>
  <ConfigProvider :theme="{ token: { paddingXS: 12, colorText: '#224466', colorBgContainer: '#ffffff', colorBgContainerDisabled: '#e8f0f8' } }">
    <Space orientation="vertical"><Space><Button>Alias gap</Button><Button>Current theme</Button></Space><SpaceCompact><SpaceAddon>Scoped addon</SpaceAddon><Button type="primary">Button</Button></SpaceCompact></Space>
  </ConfigProvider>
</template>
```

---

# Spin

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/spin


## 何时使用 {#when-to-use}

显示异步操作的加载状态。spinning由调用者提供，正delay用于延迟出现以减少闪烁；关闭立即生效。

## 代码演示 {#examples}


## API

原生class、style、DOM事件和ARIA属性落在正文根元素，支持当前更新；本组件不声明业务emits或v-model。

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| spinning | 当前目标加载状态 | boolean | true |
| delay | 正且有限的毫秒数延迟显示；0、负数和非有限数不延迟 | number | 0 |
| size | 图标大小；middle/default按中号处理，default保留既有告警 | 'small' \| 'medium' \| 'middle' \| 'large' \| 'default' | 'medium' |
| description | 文案；#description存在时优先，数字0可见 | VNodeChild | - |
| fullscreen | 固定全屏覆盖层，正文保持文档流；切换不重挂内容 | boolean | false |
| percent | 未提供为不定进度；显式数字含0显示圆环并钳制到0–100；auto每200ms估算，非有限数为不定进度 | number \| 'auto' | - |
| prefixCls | 当前类名前缀，自定义CSS需预生成/加载 | string | 'apollo-spin' |
| classNames | 语义类名；Provider与本地逐槽拼接 | `SpinSemanticValue<SpinSemanticClassNames>` | - |
| styles | 语义样式；逐槽浅合并，本地优先；函数收到当前合并props | `SpinSemanticValue<SpinSemanticStyles>` | - |
| tip | 既有废弃文案别名，使用description | VNodeChild | - |
| wrapperClassName | 既有废弃包装类名；默认槽存在或全屏时作用于root | string | - |

### 插槽

| 插槽 | 作用域 | 说明 |
|---|---|---|
| default | - | 正文；条件槽新增/移除时使用当前状态 |
| indicator | { percent: number \| undefined } | 完整Vue内容，支持多节点、Fragment和原生控件；显式绑定子组件的percent，不克隆或注入用户VNode |
| description | - | 文案内容；空槽抑制prop且不创建空包装 |

具名槽按存在性优先，有意为空时抑制Provider和默认值。加载关闭时不消费指示器/文案槽。indicator的scope提供当前数值，auto为估算值，undefined表示不定进度。

### Expose与程序化配置

nativeElement为HTMLDivElement或null，指向稳定正文外壳。可通过ConfigProvider的spin配置当前className/style/classNames/styles/indicator；indicator为程序化VNode，保持其原生属性。

Spin.setDefaultIndicator(indicator: VNodeChild)与具名setDefaultIndicator设置模块默认内容；null/undefined重置为内置图标。它不主动调度更新，已挂载实例在下次实际render读取当前默认值。getDefaultIndicator返回当前配置。实例插槽优先于Provider，再使用模块默认值。

## Semantic DOM

| 槽位 | 实际落点 |
|---|---|
| root | 始终承载正文和原生attrs的根div |
| section | 始终为独立加载层；普通、嵌套、全屏切换保持同一节点 |
| indicator | 完整指示器容器，样式同时覆盖自定义内容与可见圆环 |
| description | 非空文案div |
| container | 默认槽正文容器 |
| tip | 既有废弃文案语义别名，使用description |
| mask | 全屏的实际覆盖层，与section为同一元素；关闭时隐藏且inert |

root与section样式各自独立；需要定制遮罩时用styles.mask。普通文案使用正文色，全屏文案有可读背景。内置动画遵守theme.token.motion=false和系统减少动画偏好；自定义内容的动画由调用者配置。

## 主题变量（Design Token）{#design-token}

4个Token从当前theme.components.Spin读取，动态配置、移除和恢复均生效，原生根CSS变量优先。contentHeight限制嵌套加载层最大高度，默认400，不强制正文高度且不限制全屏遮罩。

<ComponentTokenTable component="Spin"></ComponentTokenTable>


## 基础用法 (basic)

spinning默认为true。内置四点图表示不定进度。

### basic.vue

```vue
<script setup lang="ts">
import { Spin } from '@apollo-design/ui';
</script>

<template>
  <Spin />
</template>
```

## 尺寸 (size)

三档图标尺寸来自当前dotSizeSM、dotSize和dotSizeLG。嵌套实例拥有自己的尺寸。

### size.vue

```vue
<script setup lang="ts">
import type { CSSProperties } from 'vue';
import { Spin } from '@apollo-design/ui';

const rowStyle: CSSProperties = {
  display: 'flex',
  alignItems: 'center',
  gap: '16px',
  flexWrap: 'wrap',
};
</script>

<template>
  <div :style="rowStyle">
    <Spin size="small" />
    <Spin />
    <Spin size="large" />
  </div>
</template>
```

## 加载文案 (description)

description或#description提供当前文案，数字0有效。存在的空槽抑制prop且不创建空包装，关闭加载时不消费文案槽。

### description.vue

```vue
<script setup lang="ts">
import type { CSSProperties } from 'vue';
import { Spin } from '@apollo-design/ui';

const rowStyle: CSSProperties = {
  display: 'flex',
  alignItems: 'center',
  gap: '16px',
  flexWrap: 'wrap',
};
const contentStyle = {
  padding: '50px',
  background: 'var(--apollo-color-fill-quaternary)',
  borderRadius: '4px',
};
</script>

<template>
  <div :style="rowStyle">
    <Spin description="Loading" size="small">
      <div :style="contentStyle" />
    </Spin>
    <Spin description="Loading">
      <div :style="contentStyle" />
    </Spin>
    <Spin description="Loading" size="large">
      <div :style="contentStyle" />
    </Spin>
  </div>
</template>
```

## 嵌套模式 (nested)

默认槽承载正文。稳定加载层与正文共享布局区域，加载时正文变淡且不响应指针；空正文也为真实加载内容留出空间。

### nested.vue

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Alert, Checkbox, Spin } from '@apollo-design/ui';

const loading = ref(false);
</script>

<template>
  <Spin :spinning="loading">
    <Alert type="info" title="Alert message title" description="Further details about the context of this alert." />
  </Spin>
  <p :style="{ marginTop: '16px' }">
    加载状态：
    <Checkbox v-model:checked="loading">切换</Checkbox>
  </p>
</template>
```

## 延迟显示 (delay-and-debounce)

正delay延迟显示以减少闪烁；关闭立即生效。配置变化取消旧任务并重新计时，卸载清理定时器。无正delay时随Vue更新显示。

### delay-and-debounce.vue

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Alert, Checkbox, Spin } from '@apollo-design/ui';

const loading = ref(false);
</script>

<template>
  <Spin :spinning="loading" :delay="500">
    <Alert type="info" title="Alert message title" description="Further details about the context of this alert." />
  </Spin>
  <p :style="{ marginTop: '16px' }">
    加载状态（500ms 内松手则不会出现加载态）：
    <Checkbox v-model:checked="loading">切换</Checkbox>
  </p>
</template>
```

## 自定义指示符 (custom-indicator)

使用#indicator直接渲染SVG、组件、多节点或原生控件；作用域为{ percent }。内容保持原生属性，样式作用于独立指示器容器；空槽抑制默认值。

### custom-indicator.vue

```vue
<script setup lang="ts">
import type { SpinSize } from '@apollo-design/ui';
import { Spin } from '@apollo-design/ui';

const sizes = ['small', 'medium', 'large'] satisfies SpinSize[];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 16px">
    <Spin v-for="size in sizes" :key="size" :size="size">
      <template #indicator>
        <svg width="1em" height="1em" viewBox="0 0 24 24" fill="none" focusable="false" aria-hidden="true">
          <circle cx="12" cy="12" r="9" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-dasharray="42 14" />
        </svg>
      </template>
    </Spin>
    <Spin>
      <template #indicator>
        <svg width="48" height="48" viewBox="0 0 24 24" fill="none" focusable="false" aria-hidden="true">
          <circle cx="12" cy="12" r="9" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-dasharray="42 14" />
        </svg>
      </template>
    </Spin>
    <Spin :percent="42">
      <template #indicator="{ percent }"><span style="color: var(--apollo-color-text)">{{ percent }}%</span></template>
    </Spin>
  </div>
</template>
```

## 进度 (percent)

未提供percent时为不定加载；显式数字含0在首帧和SSR呈现有名称的进度环，数值及几何均钳制到0–100。auto每200ms估算，关闭或卸载时清理任务。

### percent.vue

```vue
<script setup lang="ts">
import type { CSSProperties } from 'vue';
import { onUnmounted, ref, watch } from 'vue';
import type { SpinPercent } from '@apollo-design/ui';
import { Checkbox, Spin } from '@apollo-design/ui';

/**
 * 进度。切到 `auto` 时组件自己按 200ms 一档**渐近**推进（越接近 100% 越慢），
 * 永远到不了 100% —— 这是 antd 的 `getPercent` 行为，用于「不知道还要多久」的场景。
 */
const auto = ref(false);
const percent = ref(-50);

let timer: ReturnType<typeof setTimeout> | null = null;

/**
 * 用 `watch` 而不是 `onMounted` 里的一次性 `setTimeout`，是为了与上游
 * `useEffect(..., [percent])` 同构：每次 `percent` 变化都重新排下一次。
 */
watch(
  percent,
  () => {
    if (timer) clearTimeout(timer);
    timer = setTimeout(() => {
      const next = percent.value + 5;
      percent.value = next > 150 ? -50 : next;
    }, 100);
  },
  { immediate: true },
);

onUnmounted(() => {
  if (timer) {
    clearTimeout(timer);
    timer = null;
  }
});

const mergedPercent = (): SpinPercent => (auto.value ? 'auto' : percent.value);

const toggleAuto = () => {
  auto.value = !auto.value;
  percent.value = -50;
};

const rowStyle: CSSProperties = {
  display: 'flex',
  alignItems: 'center',
  gap: '16px',
  flexWrap: 'wrap',
};
</script>

<template>
  <div :style="rowStyle">
    <Checkbox :checked="auto" @change="toggleAuto">Auto</Checkbox>
    <Spin :percent="mergedPercent()" size="small" />
    <Spin :percent="mergedPercent()" />
    <Spin :percent="mergedPercent()" size="large" />
  </div>
</template>
```

## 自定义语义结构的样式和类 (style-class)

root、section、indicator、description、container、mask均作用于各自实际容器；tip是既有文案别名。对象和函数式配置读取当前值，局部样式优先于Provider。

### style-class.vue

```vue
<script setup lang="ts">
import type { CSSProperties } from 'vue';
import type { SpinProps } from '@apollo-design/ui';
import { Spin } from '@apollo-design/ui';

/**
 * 语义化 `classNames` / `styles`：对象式与函数式两种形态。
 *
 * ⚠️ 函数式拿到的 `info.props` 是**合并后**的 props（`size` 已并入 ConfigProvider 的取值、
 *    `description` 已折成 `description ?? tip` 的结果、`percent` 是 `auto` 解析后的值），
 *    所以可以放心用它做条件分支。
 */
const classNamesObject: SpinProps['classNames'] = {
  root: 'demo-spin-root',
  indicator: 'demo-spin-indicator',
  description: 'demo-spin-description',
};

const stylesObject: SpinProps['styles'] = {
  indicator: { color: '#00d4ff' },
};

const stylesFn: SpinProps['styles'] = (info) =>
  info.props.size === 'small' ? { indicator: { color: '#722ed1' } } : {};

const rowStyle: CSSProperties = {
  display: 'flex',
  alignItems: 'center',
  gap: '16px',
  flexWrap: 'wrap',
};
</script>

<template>
  <div :style="rowStyle">
    <Spin spinning :percent="0" :class-names="classNamesObject" :styles="stylesObject" />
    <Spin spinning :percent="0" size="small" :styles="stylesFn" />
  </div>
</template>
```

## 全屏 (fullscreen)

实际mask为固定全屏覆盖层，正文和原生输入留在文档流中。切换模式保留section与内容身份；styles.mask作用于覆盖层，关闭时隐藏且inert。

### fullscreen.vue

```vue
<script setup lang="ts">
import { onUnmounted, ref } from 'vue';
import { Button, Input, Spin } from '@apollo-design/ui';

/**
 * 全屏。`fullscreen` 会加一层半透明遮罩并把转圈居中。
 *
 * ⚠️ 两条容易忽略的语义：
 *   1. 全屏覆盖层与正文分别布局，原生输入不会移位或重新挂载；
 *   2. `styles.mask` 配置覆盖层，root 仍是正文的原生外壳。
 */
const spinning = ref(false);
const percent = ref(0);
const draft = ref('Edit before loading');

let interval: ReturnType<typeof setInterval> | null = null;

const stop = () => {
  if (interval) {
    clearInterval(interval);
    interval = null;
  }
};

const showLoader = () => {
  stop();
  spinning.value = true;
  let ptg = -10;

  interval = setInterval(() => {
    ptg += 5;
    percent.value = ptg;

    if (ptg > 120) {
      stop();
      spinning.value = false;
      percent.value = 0;
    }
  }, 100);
};

onUnmounted(stop);
</script>

<template>
  <Button style="margin-bottom: 16px" @click="showLoader">Show fullscreen</Button>
  <Spin :spinning="spinning" :percent="percent" fullscreen description="Updating">
    <Input v-model:value="draft" aria-label="Fullscreen loading draft" />
  </Spin>
</template>
```

## 动态组件Token (component-token)

切换当前4个组件Token，观察三档尺寸与嵌套加载层最大高度。正文高度保持，主题移除和恢复不重建输入。内置动画遵守motion=false及系统减少动画偏好。

### component-token.vue

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Button, ConfigProvider, Input, Space, Spin } from '@apollo-design/ui';

const themed = ref(true);
const busy = ref(true);
const draft = ref('Current native draft');
</script>

<template>
  <Space wrap>
    <Button @click="themed = !themed">切换 Spin 主题</Button>
    <Button @click="busy = !busy">切换加载状态</Button>
  </Space>
  <ConfigProvider :theme="themed ? { components: { Spin: { contentHeight: 96, dotSize: 28, dotSizeSM: 12, dotSizeLG: 44 } } } : undefined">
    <div style="display: flex; align-items: center; gap: 16px; margin-top: 16px">
      <Spin size="small" /><Spin /><Spin size="large" />
    </div>
    <Spin :spinning="busy" description="Updating" style="margin-top: 16px">
      <div style="min-height: 180px; padding: 16px; background: var(--apollo-color-fill-quaternary)">
        <Input v-model:value="draft" aria-label="Spin theme draft" />
      </div>
    </Spin>
  </ConfigProvider>
</template>
```

---

# Splitter

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/splitter


可拖拽调整大小的面板分割容器。

## 何时使用

- 两侧/多栏布局需要用户手动调整占比（如 IDE 面板、详情页分栏）。
- 需要面板折叠/展开与尺寸约束（min/max）。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/splitter/demo)（10 个：basic / vertical / collapsible / multiple）。

## API

### Splitter

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| orientation | 分割方向 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| vertical | 等价 `orientation="vertical"` | `boolean` | — |
| layout | ⚠️ 已废弃：用 `orientation` | `'horizontal' \| 'vertical'` | — |
| collapsible | 折叠全局配置 `{ motion?: boolean; icon?: { start?, end? } }`（motion 开启折叠过渡动画） | — | — |
| collapsibleIcon | ⚠️ 已废弃：用 `collapsible.icon` | — | — |
| lazy | 拖拽时只移动预览线，松手才提交尺寸 | `boolean` | — |
| destroyOnHidden | 面板折叠后销毁内容（Panel 可覆盖） | `boolean` | — |
| classNames / styles | 当前对象或 `({ props: SplitterProps }) => 对象`；区域 `{ root, panel, dragger }`（dragger 类名支持 string 或 `{ default, active }`，样式支持 `{ default, active }`） | — | — |

### 事件

| 事件 | 说明 | 回调参数 |
|---|---|---|
| resizeStart | 拖拽开始 | `(sizes: number[])` |
| resize | 拖拽中 / 折叠后 | `(sizes: number[])` |
| resizeEnd | 拖拽结束 | `(sizes: number[])` |
| collapse | 折叠状态变化 | `(collapsed: boolean[], sizes: number[])` |
| draggerDoubleClick | 双击把手 | `(index: number)` |

事件由组件独占声明，`@resize-start` / `@resize-end` / `@dragger-double-click` 是模板的自然写法，`h()` 使用 `onResizeStart` / `onResizeEnd` / `onDraggerDoubleClick`。不再把通知声明为回调 prop，也不双发。`lazy` 在松手时各提交一次 `resize` 和 `resizeEnd`；取消拖拽不提交尚未接受的预览。

### 插槽

| 名称 | 说明 |
|---|---|
| default | 面板内容（`<Splitter.Panel>` 列表） |
| draggerIcon | 自定义拖拽手柄图标（替换默认 spinner；原 `draggerIcon` prop，已改为 slot） |

### Splitter.Panel

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| size | 受控尺寸（number px 或 `'50%'`） | `number \| string` | — |
| defaultSize | 非受控初始尺寸 | `number \| string` | — |
| min / max | 最小/最大尺寸（受控需配 `resize` 事件） | `number \| string` | — |
| collapsible | `boolean` 或 `{ start?, end?, showCollapsibleIcon? }`（图标显隐：`true`/`false`/`'auto'` 悬浮显隐） | — | — |
| resizable | 是否可拖拽调整 | `boolean` | `true` |
| destroyOnHidden | 折叠后销毁内容 | `boolean` | — |

### 状态、原生属性与引用

`size` 是受控提议：父级在 `resize` 中赋回新值才接受变化；拒绝提议后布局保持，撤回所有 `size` 从最后接受的尺寸继续。部分面板使用 `size` 时，其余尺寸由既有算法分配。`defaultSize` 只在该面板建立时生效；动态列表应给 Panel 稳定的业务 `key`，尺寸、折叠记忆与编辑器身份随 key 保留，移除面板会释放对应状态。

Splitter 根和 Panel 根分别接收各自的原生 `class` / `style`、`data-*`、ARIA 与原生监听器，支持 Vue 样式字符串/数组。已有 Panel `className` 别名和内部 `classNames` / `styles` 保留。Panel 的默认槽完整渲染文本、0、数组和条件内容；折叠默认保留内容，`destroyOnHidden` 才销毁内容，Panel 可覆盖容器设置。

Splitter 与实际 Panel 的 ref 均为 `{ nativeElement: HTMLDivElement | null }`，卸载后为 null。独立导出的 `SplitterPanel` 与复合 `Splitter.Panel` 是同一面板能力，应置于 Splitter 内。

### 键盘与资源

可调整 separator 通过 Tab 聚焦，沿当前布局轴的方向键调整 10px，Shift 加速为 50px；Home / End 到当前 min / max 边界，水平 RTL 镜像方向。禁用 separator 不进入 Tab 顺序。折叠按钮支持 Enter / Space；尺寸边界继续采用现有归一化和 ARIA 算法。拖拽中更改方向、lazy、禁用状态或面板 key 顺序会取消未提交的预览并释放窗口监听，卸载同时释放 ResizeObserver。动画仅为 CSS 过渡，遵循 reduced-motion。

## Theme（Component Token）

4 个（CSS 变量 `--apollo-splitter-*`）：`splitBarSize`(2px 把手宽) /
`splitTriggerSize`(6px 热区) / `resizeSpinnerSize`(20px) /
`splitBarDraggableSize`(20px)。

通过 `ConfigProvider :theme="{ components: { Splitter: { splitBarSize: 4, splitTriggerSize: 12, resizeSpinnerSize: 28 } } }"` 配置当前实例；替换、撤回和嵌套主题即时生效。未显式设置 `splitBarDraggableSize` 时继承 `resizeSpinnerSize`。原生 style 的显式 CSS 变量覆盖最后生效。前缀 DOM 响应更新，任意自定义前缀仍需预先提供对应静态 CSS。

## FAQ

**SSR / 首帧的面板尺寸是多少？**

容器未测量时使用开发者配置的原值（未配置 ⇒ `flex-basis: auto` 均分）；测量后由
归一化算法接管（`autoPtgSizes`：均分 / 缩放 / 贪婪填充，受 min/max 约束）。

**为什么 aria-valuenow 在 SSR 是 50？**

未测量时容器尺寸为 0，百分比归一化仍然成立（50/50）。


## 基本 (basic)

`Splitter.Panel` 声明面板；拖拽中间的把手调整两侧大小（未设 size 时按比例均分）。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { Splitter } from '@apollo-design/ui';
</script>

<template>
  <Splitter style="height: 200px; box-shadow: 0 0 0 1px var(--apollo-color-border)">
    <Splitter.Panel>Left</Splitter.Panel>
    <Splitter.Panel>Right</Splitter.Panel>
  </Splitter>
</template>
```

## 垂直 (vertical)

`orientation="vertical"`（等价 `vertical`）；⚠️ deprecated 的 `layout` 同样可用但会告警。

### vertical.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 vertical demo
import { Splitter } from '@apollo-design/ui';
</script>

<template>
  <Splitter orientation="vertical" style="height: 200px; box-shadow: 0 0 0 1px var(--apollo-color-border)">
    <Splitter.Panel>Top</Splitter.Panel>
    <Splitter.Panel>Bottom</Splitter.Panel>
  </Splitter>
</template>
```

## 可折叠 (collapsible)

`collapsible` 显示折叠按钮（悬浮显隐）；折叠/展开有尺寸记忆；`min` 限制最小尺寸。

### collapsible.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 collapsible demo
import { Splitter } from '@apollo-design/ui';
</script>

<template>
  <Splitter style="height: 200px; box-shadow: 0 0 0 1px var(--apollo-color-border)">
    <Splitter.Panel collapsible min="20%" default-size="40%">Left</Splitter.Panel>
    <Splitter.Panel collapsible>Right</Splitter.Panel>
  </Splitter>
</template>
```

## 多面板 (multiple)

3+ 个面板：`size`/`defaultSize` 混用，受控尺寸需配 `onResize`；`max` 限制最大占比。

### multiple.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 multiple demo（多面板 + min/max）
import { Splitter } from '@apollo-design/ui';
</script>

<template>
  <Splitter style="height: 200px; box-shadow: 0 0 0 1px var(--apollo-color-border)">
    <Splitter.Panel collapsible default-size="20%" min="10%">Left</Splitter.Panel>
    <Splitter.Panel default-size="40%">Center</Splitter.Panel>
    <Splitter.Panel max="60%" collapsible>Right</Splitter.Panel>
  </Splitter>
</template>
```

## 尺寸约束 (size)

`default-size`、`min`、`max` 使用数值表示像素（例如 `:min="100"`），使用百分比字符串表示比例（例如 `min="20%"`）。下方实时显示 `resize` 事件的像素尺寸。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size demo：defaultSize 支持百分比 / 像素，min / max 限制拖拽范围
import { Splitter } from '@apollo-design/ui';
import { ref } from 'vue';

const sizes = ref<number[]>([]);

const onResize = (next: number[]) => {
  sizes.value = next;
};
</script>

<template>
  <Splitter style="height: 200px; box-shadow: 0 0 0 1px var(--apollo-color-border)" @resize="onResize">
    <Splitter.Panel default-size="30%" min="20%" max="50%">30% / min 20% / max 50%</Splitter.Panel>
    <Splitter.Panel :default-size="200" :min="100" :max="300">200px 初始宽度</Splitter.Panel>
    <Splitter.Panel>剩余空间</Splitter.Panel>
  </Splitter>
  <p>
    当前面板尺寸（px）：{{ sizes.map((size) => Math.round(size)).join(' / ') || '拖动分隔条查看' }}
  </p>
</template>
```

## 受控模式 (control)

通过 `size` 受控 + `resize` 事件同步面板尺寸，按钮可快速切换预设比例。

父级接受 `resize` 的尺寸提议才改变受控布局；撤回 `size` 后从最后接受的布局继续拖动，重置按钮重新设置明确比例。

The parent accepts size proposals through `resize`. Removing `size` continues from the last accepted layout; reset assigns an explicit ratio again.

### control.vue

```vue
<script setup lang="ts">
// 接受 resize 提议、显式重置与撤回 size 控制。
import { Button, Flex, Splitter } from '@apollo-design/ui';
import { ref } from 'vue';

const sizes = ref<(number | string)[] | undefined>(['30%', '70%']);
const presets = [20, 30, 50];

const onResize = (next: number[]) => {
  if (sizes.value !== undefined) sizes.value = next.map((size) => Math.round(size));
};

const applyPreset = (left: number) => {
  sizes.value = [`${left}%`, `${100 - left}%`];
};

const formatSize = (size: number | string | undefined): string => {
  if (typeof size === 'number') return `${Math.round(size)}px`;
  return size ?? '-';
};
</script>

<template>
  <Flex vertical gap="middle">
    <Flex gap="small" wrap>
      <Button v-for="preset in presets" :key="preset" @click="applyPreset(preset)">
        {{ preset }} / {{ 100 - preset }}
      </Button>
      <Button @click="sizes = undefined">撤回控制</Button>
      <Button @click="applyPreset(30)">重置为 30 / 70</Button>
    </Flex>
    <Splitter style="height: 200px; box-shadow: 0 0 0 1px var(--apollo-color-border)" @resize="onResize">
      <Splitter.Panel :size="sizes?.[0]">左侧（受控 size）</Splitter.Panel>
      <Splitter.Panel :size="sizes?.[1]">右侧（受控 size）</Splitter.Panel>
    </Splitter>
    <p>当前受控尺寸：{{ sizes ? `${formatSize(sizes[0])} / ${formatSize(sizes[1])}` : '非受控，保留最后接受的比例' }}</p>
  </Flex>
</template>
```

## 延迟更新 (lazy)

`lazy` 拖动时只显示预览线，松手后才通过 `resize-end` 应用尺寸。

### lazy.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 lazy demo：拖动只预览，松手才应用
import { Splitter } from '@apollo-design/ui';
import { ref } from 'vue';

const result = ref('尚未拖动');

const onResizeEnd = (sizes: number[]) => {
  result.value = sizes.map((size) => `${Math.round(size)}px`).join(' / ');
};
</script>

<template>
  <p>开启 `lazy` 后，拖动时只显示预览线，松手才更新面板尺寸。</p>
  <Splitter lazy style="height: 200px; box-shadow: 0 0 0 1px var(--apollo-color-border)" @resize-end="onResizeEnd">
    <Splitter.Panel>左侧</Splitter.Panel>
    <Splitter.Panel>右侧</Splitter.Panel>
  </Splitter>
  <p>松手后的尺寸：{{ result }}</p>
</template>
```

## 嵌套分组 (group)

在 `Splitter.Panel` 内再放一个垂直 `Splitter`，组合出上下 + 左右的分组布局。

### group.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 group demo：Splitter 嵌套组合
import { Splitter } from '@apollo-design/ui';
</script>

<template>
  <Splitter style="height: 300px; box-shadow: 0 0 0 1px var(--apollo-color-border)">
    <Splitter.Panel default-size="40%">
      <Splitter vertical style="height: 100%">
        <Splitter.Panel default-size="50%">左上</Splitter.Panel>
        <Splitter.Panel default-size="50%">左下</Splitter.Panel>
      </Splitter>
    </Splitter.Panel>
    <Splitter.Panel>
      <Splitter vertical style="height: 100%">
        <Splitter.Panel default-size="50%">右上</Splitter.Panel>
        <Splitter.Panel default-size="50%">右下</Splitter.Panel>
      </Splitter>
    </Splitter.Panel>
  </Splitter>
</template>
```

## 自定义拖拽手柄 (customize)

`#draggerIcon` 插槽替换默认手柄图标；面板可用原生 `class` 设置背景。

### customize.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 customize demo：自定义拖拽手柄 + 面板样式
import { HolderOutlined } from '@apollo-design/icons';
import { Splitter } from '@apollo-design/ui';
import { ref } from 'vue';

const sizeText = ref('拖动分隔条查看尺寸');

const onResizeEnd = (sizes: number[]) => {
  sizeText.value = sizes.map((size) => `${Math.round(size)}px`).join(' / ');
};
</script>

<template>
  <Splitter
    style="height: 200px; box-shadow: 0 0 0 1px var(--apollo-color-border)"
    @resize-end="onResizeEnd"
  >
    <Splitter.Panel class="demo-splitter-panel-a" default-size="50%">自定义拖拽手柄</Splitter.Panel>
    <Splitter.Panel class="demo-splitter-panel-b" default-size="50%">右侧面板</Splitter.Panel>
    <template #draggerIcon>
      <HolderOutlined />
    </template>
  </Splitter>
  <p>松手后的尺寸：{{ sizeText }}</p>
</template>

<style scoped>
.demo-splitter-panel-a {
  padding: 12px;
  background: var(--apollo-color-primary-bg);
}

.demo-splitter-panel-b {
  padding: 12px;
  background: var(--apollo-color-success-bg);
}
</style>
```

## 自定义折叠图标 (collapsible-icon)

`collapsible.icon` 定制起止图标并开启 `motion`，`collapse` 事件回传各面板折叠状态。

### collapsible-icon.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 collapsible-icon demo：collapsible.icon + motion
import { DoubleLeftOutlined, DoubleRightOutlined } from '@apollo-design/icons';
import { Splitter } from '@apollo-design/ui';
import { h, ref } from 'vue';

const collapsible = {
  motion: true,
  icon: {
    start: h(DoubleLeftOutlined),
    end: h(DoubleRightOutlined),
  },
};

const collapsedText = ref('尚未折叠');

const onCollapse = (collapsed: boolean[]) => {
  collapsedText.value = collapsed
    .map((item, index) => `面板 ${index + 1}：${item ? '已折叠' : '已展开'}`)
    .join('，');
};
</script>

<template>
  <Splitter
    style="height: 200px; box-shadow: 0 0 0 1px var(--apollo-color-border)"
    :collapsible="collapsible"
    @collapse="onCollapse"
  >
    <Splitter.Panel collapsible default-size="40%">左侧（可折叠）</Splitter.Panel>
    <Splitter.Panel collapsible>右侧（可折叠）</Splitter.Panel>
  </Splitter>
  <p>悬浮到分隔条后点击双箭头：{{ collapsedText }}</p>
</template>
```

---

# Statistic

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/statistic


展示统计数值；Timer按目标时间计时。内容通过Vue插槽表达，数值与计时由调用者传入，没有v-model或内置数字动画。

## 代码演示

原7个示例包含基本值/骨架、单位、卡片布局、原生值格式化、可重启/切换方向的计时、语义样式和当前组件Token。`animated`保留原链接，实际演示自定义数值格式；不声称内置动画。

## Statistic Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | 当前类名前缀；任意自定义前缀需自行提供对应静态CSS | `string` | Provider前缀+`-statistic` |
| value | 原始数值；非数字文本原样显示 | `number \| string` | `0` |
| title / prefix / suffix | 文本后备；同名槽存在时优先，空槽也压制后备 | `string` | — |
| precision | 截取/补零的小数位，负数取0，小数向零取整，非有限数忽略；不执行四舍五入 | `number` | 保留原小数 |
| decimalSeparator | 小数点文本 | `string` | `'.'` |
| groupSeparator | 字面分组文本（包括`$`），不解释替换转义 | `string` | `','` |
| loading | 骨架代替数值正文；根为aria-busy，装饰性骨架不进可访问树；正文恢复时重建 | `boolean` | `false` |
| valueStyle | 既有废弃别名；`styles.content`优先，初始化传入时保留既有开发警告 | `CSSProperties` | — |
| classNames / styles | 七语义落点的对象或`({ props }) => 对象`；读取当前props与Provider | 见导出类型 | — |
| onMouseenter / onMouseleave | 根元素原生鼠标监听，也可写`@mouseenter`/`@mouseleave` | `(event: MouseEvent) => void` | — |

### Slots

| 插槽 | 作用域 | 说明 |
|---|---|---|
| title / prefix / suffix | 无 | 完整Vue内容；有意为空不会回退文本prop |
| value | `{ value: number \| string, text: string }` | 原始值和按当前精度/分隔符格式化的文本；直接使用模板/原生控件，不传内部VNode |

```vue
<Statistic :value="balance" :precision="2">
  <template #value="{ value, text }">
    <strong>{{ text }}</strong><small>{{ currency }}</small>
  </template>
</Statistic>
```

数值槽保留`value`语义容器及其class/style；空槽得到空容器。变化的value、格式和相邻槽不替换槽内原生输入；切换loading会卸载正文。

## Statistic.Timer / StatisticTimer

共用上述展示字段、三个文本槽和七语义落点；不接受数值专属的precision/decimalSeparator/groupSeparator。计时文本使用format，自定义内容使用`#value`。

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 必填方向，可动态切换 | `'countdown' \| 'countup'` | — |
| value | 目标时间戳或Date可解析字符串；倒计时传未来、正计时传过去 | `number \| string` | `0` |
| format | Y/M/D/H/m/s/S单位、重复字母补零、`[字面文本]`转义；年/月按固定365/30天计算 | `string` | `'HH:mm:ss'` |

| 事件 | 载荷 | 时机 |
|---|---|---|
| change | 非负毫秒`number` | 挂载后立即及每帧（约1000/60ms）更新；无效目标和SSR不触发 |
| finish | 无 | countdown到0时每周期一次，在change(0)之后停止；修改目标或方向开启新周期 |

Timer的`#value`作用域为`{ value, text, duration, type }`。value为目标原值，duration为当前非负毫秒；挂载前或日期无效时为null，text为`'-'`。其它三个槽直接转发。

SSR与客户端水合首帧均为`'-'`，挂载后使用当前Date.now启动定时器；无效日期不调度，恢复有效目标后重新启动，卸载清理。format变化不重新触发已结束周期。后台标签页可能降低回调频率，每次读实际时间，不累计帧误差。

### Statistic.Countdown / StatisticCountdown

既有固定倒计时导出，支持相同的展示字段、format、槽、事件及ref；无需传type。保留既有开发废弃提示，不新增兼容函数通道。具名导出和静态子组件引用相同实现，均有真实类型。

## Attrs、Ref、Provider与主题

三个组件的class/style、id/tabindex、ARIA/data及普通原生监听均落实际根div；style支持字符串、数组和对象。Timer的change/finish是业务事件，内部原生输入的change不会冒充时长通知。`nativeElement: HTMLDivElement | null`返回实际根，卸载后为null。

七落点为root/header/title/content/value/prefix/suffix。Provider使用`components.statistic`的className/style/classNames/styles；当前配置替换或删除即时生效，局部语义配置优先，原生attrs样式最后覆盖。源主题使用`theme.components.Statistic`；最近Provider、RTL与相邻实例保持隔离。

| Component Token | 默认值 | CSS变量 |
|---|---|---|
| titleFontSize | 当前fontSize（默认14） | `--apollo-statistic-title-font-size` |
| contentFontSize | 当前fontSizeHeading3（默认24） | `--apollo-statistic-content-font-size` |

两Token接受非负有限数字，动态删除后恢复当前Alias。原生CSS变量优先，源主题变化不替换编辑器。自定义色值的对比度由调用者负责；没有默认60Hz aria-live播报，调用者可按业务选择通知方式。


## 基本 (basic)

简单展示数值。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo（components/statistic/demo/basic.tsx）
import { Col, Row, Statistic } from '@apollo-design/ui';
</script>

<template>
  <Row :gutter="[16, 16]">
    <Col :xs="24" :sm="12">
      <Statistic title="Active Users" :value="112893" />
    </Col>
    <Col :xs="24" :sm="12">
      <Statistic title="Account Balance (CNY)" :value="112893" :precision="2" />
    </Col>
    <Col :xs="24" :sm="12">
      <Statistic title="Active Users" :value="112893" loading />
    </Col>
  </Row>
</template>
```

## 前后缀 (unit)

通过 `prefix` / `suffix` 设置前后缀。

### unit.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 unit demo（components/statistic/demo/unit.tsx）
import { LikeOutlined } from '@apollo-design/icons';
import { Col, Row, Statistic } from '@apollo-design/ui';
</script>

<template>
  <Row :gutter="[16, 16]">
    <Col :xs="24" :sm="12">
      <Statistic title="Feedback" :value="1128">
        <template #prefix>
          <LikeOutlined />
        </template>
      </Statistic>
    </Col>
    <Col :xs="24" :sm="12">
      <Statistic title="Unmerged" :value="93" suffix="/ 100" />
    </Col>
  </Row>
</template>
```

## 卡片内使用 (card)

在卡片内展示统计数值。

### card.vue

```vue
<script setup lang="ts">
// 两种轻量卡片布局，突出统计数值与方向。
import { ArrowDownOutlined, ArrowUpOutlined } from '@apollo-design/icons';
import { Col, Row, Statistic } from '@apollo-design/ui';
</script>

<template>
  <Row :gutter="[16, 16]">
    <Col :xs="24" :sm="12">
      <div class="demo-statistic-card">
        <Statistic
          title="Active"
          :value="11.28"
          :precision="2"
          :styles="{ content: { color: '#3f8600', fontWeight: 700 } }"
        >
          <template #prefix>
            <ArrowUpOutlined />
          </template>
          <template #suffix>%</template>
        </Statistic>
      </div>
    </Col>
    <Col :xs="24" :sm="12">
      <div class="demo-statistic-card">
        <Statistic
          title="Idle"
          :value="9.3"
          :precision="2"
          :styles="{ content: { color: '#cf1322', fontWeight: 700 } }"
        >
          <template #prefix>
            <ArrowDownOutlined />
          </template>
          <template #suffix>%</template>
        </Statistic>
      </div>
    </Col>
  </Row>
</template>

<style scoped>
.demo-statistic-card {
  padding: 24px;
}
</style>
```

## 数值格式 (animated)

通过原生`#value="{ value, text }"`插槽展示格式化数值。数值仍来自响应式value，模板不需要包装内部VNode。

### animated.vue

```vue
<script setup lang="ts">
import { Statistic } from '@apollo-design/ui';

const formatNumber = (value: number | string, digits = 0) =>
  Number(value).toLocaleString('en-US', {
    minimumFractionDigits: digits,
    maximumFractionDigits: digits,
  });
</script>

<template>
  <div class="demo-statistic-animated">
    <Statistic title="Active Users" :value="112893" :class-names="{ content: 'demo-statistic-tabular' }">
      <template #value="{ value }">{{ formatNumber(value) }}</template>
    </Statistic>
    <Statistic title="Account Balance (CNY)" :value="112893" :class-names="{ content: 'demo-statistic-tabular' }">
      <template #value="{ value }">{{ formatNumber(value, 2) }}</template>
    </Statistic>
  </div>
</template>

<style scoped>
.demo-statistic-animated { display: flex; flex-wrap: wrap; gap: 24px; }
</style>
<style>
.demo-statistic-tabular { font-variant-numeric: tabular-nums; }
</style>
```

## 倒计时 / 正计时 (timer)

通过`Statistic.Timer`展示倒计时或正计时；重启短周期、切换方向，检查原生输入在计时中保留，完成次数每周期只增加一次。

### timer.vue

```vue
<script setup lang="ts">
import { Button, Input, Space, Statistic, type TimerType } from '@apollo-design/ui';
import { ref } from 'vue';

const deadline = Date.now() + 1000 * 60 * 60 * 24 * 2 + 1000 * 30; // 两天后
const before = Date.now() - 1000 * 60 * 60 * 24 * 2 + 1000 * 30; // 两天前
const shortTarget = ref(Date.now() + 10_000);
const type = ref<TimerType>('countdown');
const finishes = ref(0),
  draft = ref('Saved clock draft');
const onFinish = () => {
  finishes.value++;
};
const restart = () => {
  type.value = 'countdown';
  shortTarget.value = Date.now() + 1500;
};
const switchDirection = () => {
  type.value = type.value === 'countdown' ? 'countup' : 'countdown';
  shortTarget.value = Date.now() + (type.value === 'countdown' ? 5000 : -5000);
};
</script>

<template>
  <Space wrap style="margin-bottom:16px">
    <Button @click="restart">Restart short countdown</Button>
    <Button @click="switchDirection">Switch clock direction</Button>
    <output aria-label="Completed countdowns">{{ finishes }}</output>
  </Space>
  <div class="demo-statistic-timer">
    <Statistic.Timer
      type="countdown"
      :value="deadline"
      :class-names="{ content: 'demo-statistic-tabular' }"
      @finish="onFinish"
    />
    <Statistic.Timer
      type="countdown"
      title="Milliseconds"
      :value="deadline"
      format="HH:mm:ss:SSS"
      :class-names="{ content: 'demo-statistic-tabular' }"
    />
    <Statistic.Timer
      :type="type"
      title="Interactive clock"
      :value="shortTarget"
      @finish="onFinish"
      :class-names="{ content: 'demo-statistic-tabular' }"
    >
      <template #value="{ text, duration }">
        <span data-clock-text>{{ text }}</span>
        <Input v-model:value="draft" aria-label="Clock draft" style="display:block;width:150px;max-width:100%;font-size:14px" />
        <small data-clock-duration style="font-size:12px">{{ duration === null ? 'Starting' : 'Running' }}</small>
      </template>
    </Statistic.Timer>
    <Statistic.Timer
      type="countup"
      title="Countup"
      :value="before"
      :class-names="{ content: 'demo-statistic-tabular' }"
    />
    <div class="demo-statistic-timer-row">
      <Statistic.Timer
        type="countdown"
        title="Day Level (Countdown)"
        :value="deadline"
        format="D 天 H 时 m 分 s 秒"
        :class-names="{ content: 'demo-statistic-tabular' }"
      />
    </div>
    <div class="demo-statistic-timer-row">
      <Statistic.Timer
        type="countup"
        title="Day Level (Countup)"
        :value="before"
        format="D 天 H 时 m 分 s 秒"
        :class-names="{ content: 'demo-statistic-tabular' }"
      />
    </div>
  </div>
</template>

<style scoped>
.demo-statistic-timer {
  display: flex;
  flex-wrap: wrap;
  gap: 24px;
}
.demo-statistic-timer-row {
  width: 100%;
}
</style>

<style>
.demo-statistic-tabular {
  font-variant-numeric: tabular-nums;
}
</style>
```

## 语义化样式 (style-class)

`classNames` / `styles` 支持对象与函数两种形态。

### style-class.vue

```vue
<script setup lang="ts">
// 对象与函数语义样式；标题跟随当前主题，数值色块使用成对的前景/背景。
import { Statistic } from '@apollo-design/ui';

const classNames = { root: 'demo-statistic-root' };

const styleFn = ({ props }: { props: { value?: number | string } }) => {
  const numValue = Number(props.value ?? 0);
  const isNegative = Number.isFinite(numValue) && numValue < 0;
  if (isNegative) {
    return {
      title: { color: 'var(--apollo-color-text-heading)' },
      content: { color: 'var(--apollo-color-text-heading)' },
      value: {
        backgroundColor: '#fff1f0',
        color: '#a8071a',
        borderRadius: '4px',
        paddingInline: '6px',
        userSelect: 'none' as const,
      },
    };
  }
  return {};
};
</script>

<template>
  <div class="demo-statistic-style-list">
    <Statistic
      :class-names="classNames"
      title="Monthly Active Users"
      :value="93241"
      prefix="↑"
      suffix="users"
      :styles="{
        title: { color: 'var(--apollo-color-text-heading)', fontWeight: 600 },
        content: { fontSize: '24px' },
        value: {
          backgroundColor: '#e6f4ff',
          borderRadius: '4px',
          color: '#0958d9',
          paddingInline: '6px',
          userSelect: 'none',
        },
      }"
    />
    <Statistic
      :class-names="classNames"
      title="Yearly Loss"
      :value="-18.7"
      :precision="1"
      :styles="styleFn"
      suffix="%"
    />
  </div>
</template>

<style scoped>
.demo-statistic-style-list {
  display: flex;
  flex-direction: column;
  gap: 24px;
}
</style>

<style>
.demo-statistic-root {
  border: 2px dashed #ccc;
  padding: 16px;
  border-radius: 8px;
}
</style>
```

## 组件 Token (component-token)

源主题`components.Statistic`控制两种字号；切换主题可移除/恢复，滑块更新当前字号，原生CSS变量覆盖优先。观察原生输入在配置切换中保持。

### component-token.vue

```vue
<script setup lang="ts">
import {
  Button,
  Checkbox,
  ConfigProvider,
  Input,
  Slider,
  Space,
  Statistic,
} from '@apollo-design/ui';
import { computed, ref } from 'vue';

const contentFontSize = ref(36),
  source = ref(true),
  native = ref(false),
  draft = ref('Current theme');
const theme = computed(() =>
  source.value
    ? { components: { Statistic: { titleFontSize: 16, contentFontSize: contentFontSize.value } } }
    : undefined,
);
const tokenStyle = computed(() =>
  native.value
    ? {
        '--apollo-statistic-title-font-size': '19px',
        '--apollo-statistic-content-font-size': '48px',
      }
    : undefined,
);
</script>

<template>
  <div>
    <Space wrap style="margin-bottom: 16px">
      <Button @click="source = !source">Toggle Statistic theme</Button>
    <Checkbox v-model:checked="native" aria-label="Native Statistic token override">Native override</Checkbox>
    </Space>
    <ConfigProvider :theme="theme">
      <Statistic title="Active Users" :value="112893" :style="tokenStyle">
        <template #value="{ text }">
          <span data-token-value>{{ text }}</span>
          <Input v-model:value="draft" aria-label="Statistic token draft" style="display:block;width:160px;max-width:100%;font-size:14px" />
        </template>
      </Statistic>
    </ConfigProvider>
    <div style="max-width:320px;margin-top:24px">
      <span style="color:var(--apollo-color-text-secondary)">数值字号：{{ contentFontSize }}px</span>
      <Slider v-model:value="contentFontSize" :min="20" :max="64" aria-label-for-handle="Statistic content font size" />
    </div>
  </div>
</template>
```

---

# Steps

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/steps


引导用户按照流程完成任务的导航条。

## 何时使用

- 任务需要分步执行，且步骤间有先后顺序。
- 需要向用户展示当前所处的流程位置与整体进度。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/steps/demo)（21 个，包含原生作用域槽场景）。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| items | 步骤数据（`title/subTitle/content/icon/status/disabled/onClick` 等；VNode 经 `h()` 程序化传入） | `StepItem[]` | — |
| type | 类型 | `'default' \| 'navigation' \| 'inline' \| 'panel' \| 'dot'` | `'default'` |
| variant | 变体 | `'filled' \| 'outlined'` | `'filled'` |
| size | 尺寸（`default` 已废弃 ⇒ `medium`） | `'small' \| 'medium' \| 'middle' \| 'default'` | `'middle'` |
| orientation | 方向 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| titlePlacement | 标题位置（dot/vertical 下自动推导） | `'horizontal' \| 'vertical'` | `'horizontal'` |
| current | 当前步（从 0 计），支持 `v-model:current` | `number` | `0` |
| initial | 起始序号 | `number` | `0` |
| status | 当前步状态覆盖 | `'wait' \| 'process' \| 'finish' \| 'error'` | `'process'` |
| percent | 当前 process 步的进度环百分比 | `number` | — |
| maxCount | 最大展示步数（≥3，隐藏区段折叠为省略步） | `number` | — |
| responsive | 窄屏自动转竖向 | `boolean` | `true` |
| ellipsis / offset | 省略模式 / inline 偏移 | `boolean` / `number` | — |
| prefixCls | DOM 类名前缀，自定义值需配套静态样式 | `string` | `'apollo-steps'` |
| classNames / styles | 十个语义区域的类名/样式，支持读取当前解析后 props 的函数 | `StepsProps['classNames']` / `StepsProps['styles']` | — |
| direction / labelPlacement / progressDot | ⚠️ 已废弃（`orientation` / `titlePlacement` / `type="dot"`） | — | — |

### Events

| 事件 | 说明 | 参数 |
|---|---|---|
| change | 请求切换到不同步骤；监听此事件使非禁用步骤可点击并支持 Enter/空格 | `(current: number)` |
| update:current | `v-model:current` 更新请求，也启用非禁用步骤的点击和键盘操作 | `(current: number)` |

`current` 始终由父级控制，事件只提出请求；父级未更新时当前步骤保持不变。模板可直接使用 `v-model:current`，或使用 `@change`，支持 `.once` 和监听器数组。原生根节点的 `change` 不会触发该业务事件；根 `@click` 仍接收原生 MouseEvent。`items.onClick` 是数据项回调，接收 MouseEvent，禁用项不会调用。

### Slots

| 插槽 | 说明 | 参数 |
|---|---|---|
| #iconRender | 自定义图标渲染（替换默认图标节点） | `{ iconNode, index, active, item }` |
| #itemRender | 包装整步节点 | `{ itemNode, index, active, item }` |
| #itemWrapperRender | 包装 wrapper 层 | `{ itemNode }` |
| #progressDot | 点状步骤点自定义渲染（deprecated `progressDot` 函数形态的对应物） | `{ iconNode, index, status, title, description, content }` |

> ⚠️ C8-R2：antd 的 `iconRender` / `itemRender` / `itemWrapperRender` /
> `progressDot(fn)` 在本仓**一律是作用域插槽**，不保留同名 prop。`items` 数组字段
> （`icon` 等）是数据 API，`h()` 程序化传 VNode 合法。

四个槽均接收表中单个具名对象，组件声明与原生Vue模板可精确推断作用域；返回值为VNodeChild。显式空槽覆盖对应节点，动态移除恢复默认渲染。items提供条目数据，不提供未实现的默认内容槽；之前StepsSlots.default的空声明已直接移除。内联模式有正文时默认显示Tooltip，无需额外itemRender；自定义itemRender也能安全渲染itemNode。详见[原生槽记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/steps-native-slots.md)。

## 设计说明

- **rc-steps 1.2.3 内核的 Vue 自建**（Steps/Step/StepIcon/Rail + useDisplaySteps 折叠算法）。
- **maxCount 折叠**：首/末/当前恒保留，其余按「当前左侧、当前右侧、首右侧、末左侧」
  距离优先补位；非连续区段渲染为禁用省略步（status 反映区段内 error/进度）。
- **rail 语义**：连线 status 取 **nextStatus**（通向下一步）。
- **差异**：Wave 点击波纹未实现（wave 基建缺失）、`components` 注入未接（app 壳），
  见组件 README。

## 响应性

items、current、initial 和 maxCount 变化后重新派生可见项、折叠和当前状态，点击动作使用当前索引。class/style 在 render 中读取，支持 Vue 字符串、对象和数组 style；同名 styles.root 仍按既有顺序覆盖原生 style。classNames/styles 支持文档化的函数形态，读取当前解析后的 props。Steps 没有 large 尺寸，全局 large 默认值按 medium 解析。

responsive 可在挂载后由 false 切为 true，立即按当前视口调整方向，无需等待 resize；再关闭时恢复显式/默认方向。

## 主题 Token

`ConfigProvider.theme.components.Steps` 支持 `descriptionMaxWidth`、`customIconFontSize`、`iconSize`、`iconFontSize`、`dotSize`、`dotCurrentSize`、`navArrowColor`、`navContentMaxWidth`、`iconSizeSM` 九个实际消费字段。组件在自身根节点消费当前主题，支持替换、移除和嵌套作用域；`descriptionMaxWidth` 已废弃但仍保留现有行为。显式原生 style 和 styles.root 可覆盖同名主题变量，styles.root 继续最后生效。图标数据 `0` 显示为零，`false`/空字符串有意隐藏图标；省略 icon 后恢复默认序号。

开发版 `0.0.0` 直接移除 `customIconSize`、`customIconTop`、`iconTop`、`titleLineHeight` 四个无效历史 Token：旧设置从未被 CSS 消费，现不再声明或生成。请使用 `iconSize`/`customIconFontSize` 或现有语义 styles 定制图标；不提供兼容层或弃用期。原 `onChange` 手调通道统一由 Vue `change` emits 处理，`h(Steps, { onChange })` 写法与数字载荷保持，模板使用 `@change`。


## clickable (clickable)

监听 `@change` 后，步骤条变为可点击状态（`role="button"` + 键盘可操作）；父级接受请求后更新 `current`。

### clickable.vue

```vue
<script setup lang="ts">
import { Steps } from '@apollo-design/ui';
import { ref } from 'vue';

const current = ref(1);
const items = [
  { title: '登录', content: '第一步' },
  { title: '下单', content: '第二步' },
  { title: '支付', content: '第三步' },
];
</script>

<template>
  <Steps v-model:current="current" :items="items" />
</template>
```

## component-token (component-token)

通过 ConfigProvider 覆盖 Steps 的图标尺寸和自定义图标字号。组件直接消费当前作用域 Token，后续替换主题也会更新。

### component-token.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/component-token.tsx
import { ConfigProvider, Steps } from '@apollo-design/ui';
import { h } from 'vue';

const items = [
  { title: '第一步', content: '说明' },
  { title: '第二步', content: '说明', icon: h('span', '2') },
];
</script>

<template>
  <ConfigProvider
    :theme="{ components: { Steps: { iconSize: 40, customIconFontSize: 20 } } }"
  >
    <Steps :items="items" :current="1" />
  </ConfigProvider>
</template>
```

## customized-progress-dot (customized-progress-dot)

`#progressDot` 作用域插槽自定义点状步骤点（接收 `index/status/title/content`）。

### customized-progress-dot.vue

```vue
<script setup lang="ts">
import { Steps } from '@apollo-design/ui';

const items = [{ title: '等待中' }, { title: '处理中' }, { title: '已发货' }, { title: '已完成' }];
</script>

<template>
  <Steps :items="items" type="dot" :current="2">
    <template #progressDot="{ index, status }">
      <span :style="{
        display: 'inline-flex', width: '16px', height: '16px', borderRadius: '50%',
        background: status === 'finish' ? 'var(--apollo-color-primary)' : status === 'process' ? 'var(--apollo-color-primary-bg)' : 'var(--apollo-color-fill-secondary)',
        color: status === 'finish' ? 'var(--apollo-color-text-light-solid)' : 'var(--apollo-color-text)', fontSize: '10px', alignItems: 'center', justifyContent: 'center',
      }">{{ index + 1 }}</span>
    </template>
  </Steps>
</template>
```

## error (error)

使用 `status: 'error'` 指定某一步骤为错误状态。

### error.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/error.tsx

import type { StepItem } from '@apollo-design/ui';
import { Steps } from '@apollo-design/ui';

const items: StepItem[] = [
  { title: '下载', content: '下载安装包' },
  { title: '安装', content: '运行安装程序', status: 'error' },
  { title: '完成', content: '安装完成' },
];
</script>

<template>
  <Steps :items="items" :current="1" />
</template>
```

## icon (icon)

通过 `items.icon` 自定义图标（数据 API，`h()` 程序化传 VNode）。

### icon.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/icon.tsx（items 数据 API 的 VNode 字段 —— 程序化上下文，C8-R2 豁免）
import { SmileOutlined, UserOutlined } from '@apollo-design/icons';
import { Steps } from '@apollo-design/ui';
import { h } from 'vue';

const items = [
  { title: '登录', icon: h(UserOutlined), content: '使用账号登录' },
  { title: '人脸识别', icon: h(SmileOutlined), content: '进行人脸识别验证' },
];
</script>

<template>
  <Steps :items="items" :current="0" />
</template>
```

## inline (inline)

行内步骤条（`type="inline"`，content 走 Tooltip）。

### inline.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/inline.tsx
import { Steps } from '@apollo-design/ui';

const items = [
  { title: '下单', content: '2023-06-01' },
  { title: '支付', content: '2023-06-02' },
  { title: '发货', content: '2023-06-03' },
];
</script>

<template>
  <Steps type="inline" :items="items" :current="1" />
</template>
```

## max-count (max-count)

`maxCount` 限制最大展示步数（首/末/当前恒保留，其余折叠为省略步）。

### max-count.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/max-count.tsx
import { Steps } from '@apollo-design/ui';

const items = Array.from({ length: 8 }, (_, i) => ({
  title: `步骤${i + 1}`,
  content: `第 ${i + 1} 步`,
}));
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Steps :items="items" :current="4" :max-count="4" />
    <Steps :items="items" :current="7" :max-count="4" />
  </div>
</template>
```

## nav (nav)

导航类型的步骤条（`type="navigation"`）。

### nav.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/nav.tsx
import { Steps } from '@apollo-design/ui';
import { ref } from 'vue';

const current = ref(0);
const items = [
  { title: '订单详情', content: '查看订单信息' },
  { title: '物流信息', content: '查看物流状态' },
  { title: '售后', content: '申请售后' },
];
</script>

<template>
  <Steps type="navigation" :items="items" :current="current" @change="(c: number) => (current = c)" />
</template>
```

## panel (panel)

面板类型（`type="panel"`，步间箭头分隔）。

### panel.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/panel.tsx
import { Steps } from '@apollo-design/ui';

const items = [
  { title: '选择模板', content: '挑选合适模板' },
  { title: '填写内容', content: '填充你的内容' },
  { title: '发布', content: '发布你的作品' },
];
</script>

<template>
  <div role="region" aria-label="Scrollable step panels" tabindex="0" style="max-width: 100%; overflow-x: auto">
    <Steps type="panel" :items="items" :current="1" style="min-width: 600px" />
  </div>
</template>
```

## progress (progress)

`percent` 配合当前 `process` 步显示进度环。

### progress.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/progress.tsx
import { Steps } from '@apollo-design/ui';

const items = [
  { title: '步骤一', content: '这是步骤一的描述' },
  { title: '步骤二', content: '这是步骤二的描述' },
  { title: '步骤三', content: '这是步骤三的描述' },
];
</script>

<template>
  <Steps type="default" :items="items" :current="1" :percent="60" />
</template>
```

## progress-debug (progress-debug)

调试用例：percent=100 的进度环。

### progress-debug.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/progress-debug.tsx
import { Steps } from '@apollo-design/ui';

const items = [
  { title: '第一步', content: '说明' },
  { title: '第二步', content: '说明' },
];
</script>

<template>
  <Steps :items="items" :current="0" :percent="100" />
</template>
```

## progress-dot (progress-dot)

点状步骤条（`type="dot"`；函数形态自定义渲染用 `#progressDot` 作用域插槽）。

### progress-dot.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/progress-dot.tsx
import { Steps } from '@apollo-design/ui';

const items = [
  { title: '等待中', content: '请您耐心等待' },
  { title: '处理中', content: '商品正在打包' },
  { title: '已发货', content: '商品已发出' },
  { title: '已完成', content: '感谢使用' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Steps :items="items" type="dot" :current="1" />
    <Steps :items="items" type="dot" :current="1" orientation="vertical" />
  </div>
</template>
```

## simple (simple)

最简单的用法。

### simple.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/simple.tsx
import { Steps } from '@apollo-design/ui';

const items = [
  { title: '已完成', content: '这里是该步骤的说明文字' },
  { title: '进行中', content: '这里是该步骤的说明文字' },
  { title: '待运行', content: '这里是该步骤的说明文字' },
];
</script>

<template>
  <Steps :items="items" :current="1" />
</template>
```

## small (small)

`size="small"` 小号步骤条。

### small.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/small-size（size 用法）
import { Steps } from '@apollo-design/ui';

const items = [{ title: '第一步' }, { title: '第二步' }, { title: '第三步' }];
</script>

<template>
  <Steps :items="items" :current="1" size="small" />
</template>
```

## step-next (step-next)

配合按钮进行下一步操作，父级更新受控的 `current`。

### step-next.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/step-next.tsx
import { Button, Steps } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const current = ref(0);
const items = [
  { title: '填写订单', content: '请填写收货地址与联系方式' },
  { title: '付款', content: '支持多种支付方式' },
  { title: '发货', content: '付款后 24 小时内发货' },
  { title: '签收', content: '请记得查收商品' },
];
const description = computed(() => (current.value < items.length - 1 ? '下一步' : '全部完成'));
const prev = () => {
  current.value = Math.max(0, current.value - 1);
};
const next = () => {
  current.value = Math.min(items.length - 1, current.value + 1);
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Steps :items="items" :current="current" />
    <div style="display: flex; gap: 8px">
      <Button :disabled="current === 0" @click="prev">上一步</Button>
      <Button type="primary" :disabled="current >= items.length - 1" @click="next">
        {{ description }}
      </Button>
    </div>
  </div>
</template>
```

## steps-in-steps (steps-in-steps)

嵌套步骤（antd 原例经 panel+children 嵌套；本仓 v1 以组合近似，见 README）。

### steps-in-steps.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/steps-in-steps.tsx（嵌套；v1 以两个独立 Steps 组合近似展示）
import { Steps } from '@apollo-design/ui';

const outer = [
  { title: '阶段一', content: '准备' },
  { title: '阶段二', content: '执行' },
];
const inner = [{ title: '子步骤 1' }, { title: '子步骤 2' }];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 24px">
    <Steps :items="outer" :current="1" />
    <Steps :items="inner" :current="0" size="small" />
  </div>
</template>
```

## style-class (style-class)

语义化 `classNames` / `styles`。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx（语义 classNames / styles）
import { Steps } from '@apollo-design/ui';

const items = [
  { title: '第一步', content: '说明' },
  { title: '第二步', content: '说明' },
];
</script>

<template>
  <Steps
    :items="items"
    :current="1"
    :class-names="{ root: 'demo-steps-root', itemTitle: 'demo-steps-title' }"
    :styles="{ itemIcon: { fontSize: '18px' } }"
  />
</template>
```

## title-placement (title-placement)

标题竖排（`titlePlacement="vertical"`；deprecated `labelPlacement` 同效）。

### title-placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/title-placement.tsx
import { Steps } from '@apollo-design/ui';

const items = [
  { title: '第一步', content: '请填写信息' },
  { title: '第二步', content: '请确认信息' },
  { title: '第三步', content: '请提交' },
];
</script>

<template>
  <Steps :items="items" :current="1" title-placement="vertical" />
</template>
```

## variant-debug (variant-debug)

调试用例：`filled` / `outlined` 变体。

### variant-debug.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/variant-debug.tsx
import { Steps } from '@apollo-design/ui';

const items = [
  { title: '第一步', content: '说明' },
  { title: '第二步', content: '说明' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Steps :items="items" :current="1" variant="filled" />
    <Steps :items="items" :current="1" variant="outlined" />
  </div>
</template>
```

## vertical (vertical)

竖直方向的步骤条（deprecated `direction` 同效）。

### vertical.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/vertical.tsx
import { Steps } from '@apollo-design/ui';

const items = [
  { title: '已完成', content: '2016-09-26' },
  { title: '进行中', content: '2016-09-27' },
  { title: '待运行', content: '2016-09-28' },
  { title: '待运行', content: '2016-09-29' },
];
</script>

<template>
  <Steps orientation="vertical" :items="items" :current="1" style="height: 220px" />
</template>
```

## 原生作用域插槽 (native-slots)

四个原生槽使用具名对象；内联模式通过原节点正常打开内容提示，不需要渲染函数。切换当前步或更新数据可观察作用域变化和输入状态保持；空槽覆盖回退。

### native-slots.vue

```vue
<script setup lang="ts">
import { Button, Input, Steps } from '@apollo-design/ui';
import { ref } from 'vue';

const custom = ref(true);
const empty = ref(false);
const current = ref(0);
const items = ref([
  { key: 'a', title: 'Alpha', content: 'Alpha details' },
  { key: 'b', title: 'Beta', content: 'Beta details' },
]);
const advance = () => {
  current.value = (current.value + 1) % items.value.length;
};
const update = () => {
  items.value = items.value.map((item) => ({ ...item, title: `${item.title}!` }));
};
</script>

<template>
  <div style="display: flex; gap: 8px; margin-bottom: 16px; flex-wrap: wrap">
    <Button @click="advance">Advance native step</Button>
    <Button @click="update">Update native step data</Button>
    <Button @click="custom = !custom">Toggle native step slots</Button>
    <Button @click="empty = !empty">Toggle empty step slots</Button>
  </div>
  <Steps data-native-inline-steps type="inline" :items="items" :current="current" :responsive="false">
    <template v-if="custom" #iconRender="{ index, active }">
      <b :data-native-icon="index" :data-active="active">{{ index + 1 }}</b>
    </template>
    <template v-if="custom" #itemWrapperRender="{ itemNode }">
      <div data-native-wrapper><component :is="itemNode" /></div>
    </template>
    <template v-if="custom" #itemRender="{ itemNode, item, index, active }">
      <div v-if="!empty" :data-native-step="item.key" :data-index="index" :data-active="active">
        <component :is="itemNode" />
        <Input :aria-label="`Step note ${item.key}`" style="width: 80px" />
      </div>
    </template>
  </Steps>
  <Steps data-native-dot-steps type="dot" :items="items" :current="current" :responsive="false">
    <template #progressDot="{ index, status }"><span :data-native-dot="index">{{ index }}:{{ status }}</span></template>
  </Steps>
</template>
```

---

# Switch

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/switch


开关选择器。

## 何时使用

- 需要表示**开 / 关**两种状态，且切换后立即生效（不需要点「确定」）。
- 与复选框的区别：开关的语义是「立即生效的状态」，复选框是「待提交的选择」。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/switch/demo)（7 个，覆盖 antd 的主要用户场景）。

## API

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| checked | 指定当前是否选中（受控） | `boolean` | — |
| defaultChecked | 初始是否选中（非受控） | `boolean` | `false` |
| value | ⚠️ `checked` 的**别名**（antd `@since 5.12.0`） | `boolean` | — |
| defaultValue | ⚠️ `defaultChecked` 的**别名** | `boolean` | — |
| onChange | `change` 事件的监听器写法（**两个参数**；`disabled` 时不触发） | `(checked: boolean, event: MouseEvent \| KeyboardEvent) => void` | — |
| onClick | 原生 click 事件监听器；状态从 change / v-model 获取 | `(event: MouseEvent) => void` | — |
| checkedChildren | 选中时的内容 | `VNodeChild` | — |
| unCheckedChildren | 未选中时的内容 | `VNodeChild` | — |
| disabled | 失效状态 | `boolean` | — |
| loading | 加载中；⚠️ 会**强制**失效（`\|\|` 判据） | `boolean` | `false` |
| size | 尺寸；⚠️ `'default'` 已废弃（提示改用 `'medium'`） | `'small' \| 'medium' \| 'middle' \| 'default'` | — |
| autoFocus | 自动获取焦点 | `boolean` | — |
| title / id / tabIndex | 原生属性（落 `<button>`） | — | — |
| class / style | **根元素原生 attrs**（不是 Props） | — | — |
| classNames / styles | 语义槽 `{ root, content, indicator }`（对象或函数） | — | — |

`checked` 优先于 `value`；`defaultChecked` 优先于 `defaultValue`，默认值只用于初始化。受控交互只提出更新，显示状态由父级回传决定；撤销两个受控值后保留最后已接受的状态。

### Slots

| 插槽 | 说明 |
|---|---|
| checkedChildren | 选中内容；存在时优先于同名 prop，包括有意为空的内容 |
| unCheckedChildren | 未选中内容；存在时优先于同名 prop，包括有意为空的内容 |

插槽内容会随当前渲染更新；条件插槽消失时恢复同名 prop。支持文本、数字（含 `0`）、VNode 和数组。

### ConfigProvider

`components.switch` 支持 `SwitchConfig` 的 `className`、`style`、`classNames` 和 `styles`。同一区域的类名拼接，样式按 Provider `styles` → Provider 根 `style` → 组件 `styles` → 原生根 `style` 合并，后者优先；配置替换和撤销会即时生效。

未指定的 `disabled` 和 `size` 分别跟随 `componentDisabled`、`componentSize`。全局 `large` 使用 Switch 的常规 `medium` 尺寸；显式组件 prop 优先，`loading` 始终禁用交互。语义函数读取当前解析后的 `size` 和 `disabled`。

### Events

| 事件 | 说明 | 参数 |
|---|---|---|
| update:checked | `v-model:checked` 通道（与 `onChange` 同时发出） | `boolean` |
| update:value | `v-model:value` 通道（别名通道，同上） | `boolean` |
| change | 声明的 Vue 语义事件；每次点击或方向键更新时发送一次，`disabled` 时不发送 | `(checked: boolean, event: MouseEvent \| KeyboardEvent)` |
| click | 原生按钮点击，含键盘激活；方向键不合成点击 | `MouseEvent` |

`@change` 与 `onChange` 注册同一事件，不会额外监听原生 DOM `change`。`@click` 只接收原生 `MouseEvent`，支持 `.stop` / `.prevent` / `.once`；不再传旧 `(checked, event)`，无兼容层或弃用期。迁移状态读取到 `@change` 或 `v-model:checked`。

原生根 `style` 支持字符串、对象和数组，与语义 root 样式按 Vue 规则合并；调用方样式优先。
原生小写 `tabindex` / `autofocus` 同样落在按钮；同时提供时，显式 `tabIndex` / `autoFocus` prop 优先。

### 键盘

| 按键 | 行为 |
|---|---|
| `ArrowLeft` | 置为未选中（`disabled` 时不生效） |
| `ArrowRight` | 置为选中（`disabled` 时不生效） |
| `Space` / `Enter` | 原生 `<button>` 的激活行为（等价点击） |

方向键使用标准 `KeyboardEvent.key` 并阻止滚动；Space/Enter 交由按钮原生激活，只产生一次 click 和状态变更。

## Ref

| 名称 | 类型 |
|---|---|
| nativeElement | `HTMLButtonElement \| null` |
| focus / blur | `(options?: FocusOptions) => void` / `() => void` |

> ⚠️ antd 的 `ref` 直接是 `HTMLButtonElement`；本仓按组件库惯例暴露对象
> （迁移时 `ref.current.focus()` → `ref.value.focus()`）。

## Theme（Component Token）

13 个，与 antd 的 `ComponentToken` 逐字段对齐（CSS 变量形态 `--apollo-switch-*`）。

| Token | 说明 | 默认值 |
|---|---|---|
| trackHeight | 开关高度 | `22px` |
| trackHeightSM | 小号开关高度 | `16px` |
| trackMinWidth | 开关最小宽度 | `44px` |
| trackMinWidthSM | 小号开关最小宽度 | `28px` |
| trackPadding | 开关内边距 | `2px` |
| handleBg | 把手背景色 | `#fff` |
| handleShadow | 把手阴影 | `0 2px 4px 0 rgba(0,35,11,0.2)` |
| handleSize | 把手大小 | `18px` |
| handleSizeSM | 小号把手大小 | `12px` |
| innerMinMargin | 内容区最小边距 | `9px` |
| innerMaxMargin | 内容区最大边距 | `24px` |
| innerMinMarginSM | 小号内容区最小边距 | `6px` |
| innerMaxMarginSM | 小号内容区最大边距 | `18px` |

这 13 项通过 `ConfigProvider.theme.components.Switch` 配置，数字长度自动补 `px`，也支持 CSS 长度字符串。没有字段覆盖时从当前全局主题派生；嵌套主题只覆盖指定字段，配置替换和撤销会更新现有按钮。旧 D50「组件 Token 不随主题更新」已修正，静态 CSS 仍保留默认值。

```vue
<ConfigProvider :theme="{ components: { Switch: { trackHeight: 14, handleSize: 20 } } }">
  <Switch aria-label="自定义开关" />
</ConfigProvider>
```

主题变量先于 Provider 样式、组件语义根样式和原生根 `style` 合并；可以通过这些根样式覆盖相应 CSS 变量。自定义 `prefixCls` 时组件变量使用当前前缀；仍须提供对应静态 CSS。

## FAQ

**禁用时点击会触发吗？**
真实用户交互及按钮的原生 `.click()` 由浏览器抑制，不发 click/change/update。显式 `dispatchEvent` 仍是普通 DOM 派发：监听器收到原生事件，但不会改变禁用状态或发送 change/update。

**`value` 和 `checked` 有什么区别？**
没有区别 —— `value` / `defaultValue` 是 `checked` / `defaultChecked` 的别名
（antd 5.12.0 起为表单场景加的）。两者同时传时 `checked` 优先。


## 基本 (basic)

最简单的用法：`defaultChecked` 非受控；`@change` 回调收到 `(checked, event)`。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
// ⚠️ 加 `aria-label`：axe 要求 `role="switch"` 有可访问名（上游同 demo 无名字，
//    那是上游自己的 a11y 缺口 —— 本仓按更严格标准，登记在 README §2）。
import { Switch } from '@apollo-design/ui';

const onChange = (checked: boolean) => {
  console.log(`switch to ${checked}`);
};
</script>

<template>
  <Switch default-checked aria-label="Switch" @change="onChange" />
</template>
```

## 不可用 (disabled)

`disabled` 让开关失效；`loading` 同样会强制失效（内部是 `||` 判据）。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 disabled demo
import { Button, Space, Switch } from '@apollo-design/ui';
import { ref } from 'vue';

const disabled = ref(true);
</script>

<template>
  <Space orientation="vertical">
    <Switch :disabled="disabled" default-checked aria-label="Disabled switch" />
    <Button type="primary" @click="disabled = !disabled">Toggle disabled</Button>
  </Space>
</template>
```

## 加载中 (loading)

`loading` 表示正在加载：把手位置显示一个转圈图标，并**强制**不可交互。

### loading.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 loading demo
import { Switch } from '@apollo-design/ui';
</script>

<template>
  <Switch loading default-checked aria-label="Loading switch" />
  <br />
  <Switch size="small" loading aria-label="Loading small switch" />
</template>
```

## 尺寸 (size)

`size="small"` 得到小号开关；`size="default"` 已废弃（会提示改用 `"medium"`）。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size demo
import { Switch } from '@apollo-design/ui';
</script>

<template>
  <Switch default-checked aria-label="Default size switch" />
  <br />
  <Switch size="small" default-checked aria-label="Small size switch" />
</template>
```

## 文字和图标 (text)

`checkedChildren` / `unCheckedChildren` 接受字符串、数字或任意节点（含图标）。

### text.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 text demo（四种 children 形态）
// C8-R2：文本走 prop，图标/富内容走 #checkedChildren / #unCheckedChildren 插槽
import { CheckOutlined, CloseOutlined, FrownOutlined, SmileOutlined } from '@apollo-design/icons';
import { Flex, Switch } from '@apollo-design/ui';
import { type Component, defineComponent, h } from 'vue';

/** 图标 + 文字的组合（antd 的 `label: <Flex gap={4} align="center">…</Flex>`）。 */
const iconLabel = (Icon: Component, text: string) =>
  h(
    Flex,
    { gap: 4, justify: 'flex-start', align: 'center' },
    {
      default: () => [h(Icon), text],
    },
  );

/** 插槽内容是 VNode —— 模板插值 `{{ }}` 会转字符串，用函数式组件承载。 */
const HappyLabel = defineComponent({ setup: () => () => iconLabel(SmileOutlined, 'Happy') });
const SadLabel = defineComponent({ setup: () => () => iconLabel(FrownOutlined, 'Sad') });
</script>

<template>
  <Flex vertical gap="medium" align="flex-start" justify="flex-start">
    <Switch checked-children="On" un-checked-children="Off" default-checked />
    <Switch default-checked>
      <template #checkedChildren>1</template>
      <template #unCheckedChildren>0</template>
    </Switch>
    <Switch default-checked>
      <template #checkedChildren><CheckOutlined /></template>
      <template #unCheckedChildren><CloseOutlined /></template>
    </Switch>
    <Switch default-checked>
      <template #checkedChildren><HappyLabel /></template>
      <template #unCheckedChildren><SadLabel /></template>
    </Switch>
  </Flex>
</template>
```

## 语义化样式 (style-class)

通过 `classNames` / `styles` 自定义三槽（root / content / indicator）；两者都支持对象与
函数两种形态，函数形态能拿到合并后的 props（如 `size`）。

最后一个开关从 `ConfigProvider.components.switch` 读取根样式和语义配置，切换时函数样式会随当前 `checked` 更新。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo（语义化三槽：root / content / indicator）
// ⚠️ PLATFORM 替换：antd 用 antd-style 的 createStyles；本仓零运行时 —— 类名与样式
//    由 demo 自己的 <style> 提供（两边生成机制本就不同，比的是挂载结果）。
import { ConfigProvider, Flex, Switch, type SwitchConfig } from '@apollo-design/ui';
import { ref } from 'vue';

/** 对象形态的 `styles`。 */
const stylesObject = {
  root: { backgroundColor: '#F5D2D2' },
  content: { color: '#4d2323' },
};

/** 函数形态的 `styles` —— 按合并后的 `size` 分支。 */
const stylesFn = (info: { props: { size?: string } }) =>
  info.props.size === 'medium'
    ? { root: { backgroundColor: '#BDE3C3' }, content: { color: '#1f3d24' } }
    : {};

const providerChecked = ref(false);
const providerConfig: SwitchConfig = {
  style: { marginInlineStart: '4px' },
  classNames: { content: 'demo-switch-content' },
  styles: ({ props }) => ({ root: { opacity: props.checked ? 1 : 0.6 } }),
};
</script>

<template>
  <Flex vertical align="flex-start" justify="flex-start" gap="medium">
    <Switch
      size="small"
      checked-children="on"
      un-checked-children="off"
      :styles="stylesObject"
      :class-names="{ root: 'demo-switch-root' }"
    />
    <Switch
      size="medium"
      checked-children="on"
      un-checked-children="off"
      :styles="stylesFn"
      :class-names="{ root: 'demo-switch-root', content: 'demo-switch-content' }"
    />
    <Switch
      default-checked
      aria-label="MUI style switch"
      :class-names="{ root: 'demo-switch-mui-root', indicator: 'demo-switch-mui-indicator' }"
    />
    <ConfigProvider :components="{ switch: providerConfig }">
      <Switch
        v-model:checked="providerChecked"
        checked-children="On"
        un-checked-children="Off"
        aria-label="Switch with Provider defaults"
      />
    </ConfigProvider>
  </Flex>
</template>

<style>
.demo-switch-root {
  width: 40px;
  background-color: #1677ff;
}
.demo-switch-content {
  font-style: italic;
}
/* MUI 风格：把轨道压扁、把手放大到轨道外（antd demo 的 muiRoot / muiIndicator） */
.demo-switch-mui-root {
  min-width: 32px;
  height: 14px;
  line-height: 14px;
}
.demo-switch-mui-root.apollo-switch-checked {
  background-color: rgba(25, 118, 210, 0.5);
}
.demo-switch-mui-root.apollo-switch-checked .apollo-switch-handle {
  inset-inline-start: calc(100% - 17px);
}
.demo-switch-mui-indicator {
  top: -3px;
  width: 20px;
  height: 20px;
  inset-inline-start: -3px;
}
.demo-switch-mui-indicator::before {
  background-color: rgb(25, 118, 210);
  border-radius: 999px;
  box-shadow:
    rgba(0, 0, 0, 0.2) 0 2px 1px -1px,
    rgba(0, 0, 0, 0.14) 0 1px 1px 0,
    rgba(0, 0, 0, 0.12) 0 1px 4px 0;
}
</style>
```

## 组件 Token (component-token)

通过 `ConfigProvider.theme.components.Switch` 覆盖组件 Token；当前配置会写入开关根元素的 CSS 变量，由静态样式消费。支持主题切换、嵌套覆盖和撤销。

覆盖 `trackHeight` / `trackMinWidth` / `trackPadding` / `handleSize` / `handleBg` /
`handleShadow` 后的效果（把手比轨道大，探出轨道外）。

### component-token.vue

```vue
<script setup lang="ts">
import type { ThemeConfig } from '@apollo-design/theme';
import { ConfigProvider, Space, Switch } from '@apollo-design/ui';

const theme: ThemeConfig = {
  token: { colorPrimary: 'rgba(25, 118, 210, 0.5)' },
  components: {
    Switch: {
      trackHeight: 14,
      trackMinWidth: 32,
      trackPadding: -3,
      handleSize: 20,
      handleBg: 'rgb(25, 118, 210)',
      handleShadow:
        'rgba(0, 0, 0, 0.2) 0px 2px 1px -1px, rgba(0, 0, 0, 0.14) 0px 1px 1px 0px, rgba(0, 0, 0, 0.12) 0px 1px 3px 0px',
    },
  },
};
</script>

<template>
  <ConfigProvider :theme="theme">
    <Space>
      <Switch default-checked aria-label="Component token switch" />
    </Space>
  </ConfigProvider>
</template>
```

---

# Table

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/table


# Table 表格

数据表格，用于展示行列数据结构。

## 何时使用

- 当有大量结构化的数据需要展现时；
- 当需要对数据进行排序、搜索、分页、自定义操作等复杂行为时。

## 引入

```ts
import { Table } from '@apollo-design/ui';
```

## 代码演示

`drag-reorder` 使用现有 onRow/onHeaderCell 钩子组合原生行/列拖放，受控更新数据和列顺序，并提供键盘可用的移动/重置按钮；不增加 Table 内建拖拽 API。

## API

### Table

| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| bordered | 是否显示外边框和列边框 | boolean | false | |
| caption | 表格的可访问性标题（`<caption>`） | VNodeChild | - | |
| columns | 列描述数据对象，见下表 | ColumnsType | - | |
| components | 覆盖表格元素的自定义渲染 | TableComponents | - | |
| dataSource | 数据数组 | T[] | - | |
| direction | 文本方向 | `'ltr' \| 'rtl'` | - | |
| expandable | 展开配置，见下表 | ExpandableConfig | - | |
| expandIconColumnIndex | 展开按钮所在列的索引（建议将 Table.EXPAND_COLUMN 放入 columns） | number | - | |
| getPopupContainer | 下拉（筛选/选择器）渲染的父节点 | (triggerNode) => HTMLElement \| ShadowRoot | - | |
| indentSize | 树形展示时每层的缩进宽度 | number | 15 | |
| loading | 页面是否加载中 | boolean \| SpinProps | false | |
| locale | 默认文案设置，见下表 | TableLocale | - | |
| pagination | 分页器配置；设为 false 时隐藏 | false \| TablePaginationConfig | 见下 | |
| rowClassName | 行的 className | string \| (record, index) => string | - | |
| rowKey | 行 key 的取值字段或生成函数 | string \| keyof T \| (record) => key | 'key' | |
| rowSelection | 行选择配置，见下表 | TableRowSelection | - | |
| scroll | 横向/纵向滚动配置（含固定列/表头） | TableScrollConfig | - | |
| showHeader | 是否显示表头 | boolean | true | |
| size | 表格尺寸 | `'large' \| 'middle' \| 'small'` | 'large' | |
| sortDirections | 支持的排序方式 | SortOrder[] | `['ascend', 'descend']` | |
| sticky | 设置粘性表头 | boolean \| TableSticky | - | |
| tableLayout | 表格布局算法（固定列/固定表头会自动置 fixed） | `'auto' \| 'fixed'` | 'auto'（固定列/表头时 'fixed'） | |
| virtual | 是否开启虚拟滚动（需配合 `scroll.x` / `scroll.y`） | boolean | false | |
| onRow | 行事件透传（click/doubleclick/mouseenter 等） | (record, index) => Record<string, unknown> | - | |
| onHeaderRow | 表头行事件透传 | (columns, index) => Record<string, unknown> | - | |

> `virtual` 需要数值型 `scroll.x`、`scroll.y`；估算行高由当前 Token 和 size 推导。

`scroll.y` 的数值以 CSS 像素为单位；`0` 保留明确的零高度表体。非虚拟表格也接受 CSS 长度字符串，移除 `scroll.y` 会取消高度限制。


### Slots

| 名称 | 作用域 | 内容 |
| --- | --- | --- |
| title / footer / summary / caption | `{ data: T[] }` | 当前页标题、底部、汇总与可访问性标题 |
| emptyText | `{ data: T[], locale }` | 空内容；存在时优先于 locale.emptyText，包括空槽 |
| expandedRow | `{ record: T, index, indent, expanded }` | 展开行内容 |
| expandIcon | `{ prefixCls, record: T, expanded, expandable, onExpand }` | 展开图标；调用 `onExpand(record, event)` 提议切换 |
| headerCell | `{ column, title }` | 现有排序/筛选外壳内的表头内容 |
| bodyCell | `{ text, record: T, index, column, originNode }` | 单元格内容，originNode 是数据 renderer 的当前结果 |
| paginationItemRender | `{ page, type, element }` | 分页项 |
| paginationTotal | `{ total, range }` | 分页总数 |
| paginationSizeChanger | PaginationSizeChangerInfo | 分页尺寸切换器 |

`columns.render/title/filterDropdown/filterIcon/sortIcon` 和选择列的 `renderCell/columnTitle` 属于每列/每项数据服务，继续保留。`shouldCellUpdate(record, previousRecord)` 控制数据 renderer 缓存；原生槽仍跟踪自己的 Vue 响应式依赖，替换列 renderer 或改变行索引会更新缓存。

汇总插槽可使用命名导出的 `Summary`、`TableSummaryRow`、`TableSummaryCell`；后两者分别对应 `Summary.Row`、`Summary.Cell`，便于原生模板和自动引入使用。

### Emits 与控制状态

| 事件 | 参数 |
| --- | --- |
| change | `(pagination, filters, sorter, { currentDataSource: T[], action })` |
| scroll | `(event: Event)`，来自当前真实表体；虚拟表体也保留原生 target |

分页 current/pageSize、列 sortOrder/filteredValue、rowSelection.selectedRowKeys 和 expandable.expandedRowKeys 各有一个接受态来源。通知携带本次提议；父组件拒绝受控提议时，界面与缓存保持接受态，撤除控制后延续最近的接受值。选择和展开配置内的业务通知保留原有职责，不另加 Table v-model。

### 泛型与 Ref

原生模板从 `dataSource: User[]` 和 `ColumnsType<User>` 推导行类型，`interface User` 无需索引签名。程序化调用使用 `h(Table<User>, props, slots)`；插槽可声明为 `TableSlots<User>`，引用使用 `TableRef`。

`nativeElement()` 返回内部表格根 HTMLElement；`scrollTo({ top })` 或 `scrollTo({ key, index, align, offset })` 操作当前表体。align 支持 start/center/end/nearest。自定义 `components.body(data, { scrollbarSize, ref, onScroll })` 应把 ref 接到真实 HTMLElement，并把原生滚动事件传给 onScroll；该显式服务优先于内置虚拟表体。

自定义元素组件应转发原生 attrs 和 default 槽。虚拟 wrapper 需要单个 HTMLElement 根；多根/纯文本组件没有可测量的滚动容器，nativeElement 为 null。更换组件或其根节点后会重新绑定真实元素与观察资源。

### 迁移

顶层 title/footer/summary/expandedRowRender/expandIcon/emptyText，以及 expandable 内 expandedRowRender/expandIcon，改为上述具名槽；位置参数改为具名作用域。`locale.emptyText` 保留静态 VNodeChild，动态内容用 #emptyText。`filterDropdownProps.dropdownRender` 改用列的 filterDropdown 数据 renderer。onRow/onCell/onHeaderCell 返回 Vue 原生 attrs，例如 onKeydown；onChange/onScroll 通过 @change/@scroll 订阅。

选择配置的 getCheckboxProps 按 type 对应真实输入，checkbox/radio change 均为 `(event: Event, checked: boolean)`；选择通知保留同一个原生事件。原生 class/style 落外层根；语义 styles 使用 Vue CSSProperties（含 undefined 与 --custom）。

### ColumnsType（列描述）

`columns` 的每一项支持分组列（`children`）与普通列，`ColumnGroupType | ColumnType`。

`onCell(record, rowIndex)` 返回原生单元格属性，包含 `colSpan`、`rowSpan` 和事件监听。跨度为 `0` 时不渲染该格，其位置必须由另一格的跨度覆盖。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| align | 列内容的对齐方式 | `'left' \| 'right' \| 'center'` | - |
| colSpan | 表头列合并（设 0 不渲染表头） | number | - |
| onCell | 单元格属性、合并跨度和原生事件 | (record: T, rowIndex) => Record<string, unknown> | - |
| onHeaderCell | 表头单元格事件透传 | (column) => Record<string, unknown> | - |
| defaultSortOrder | 默认排序顺序 | `'ascend' \| 'descend'` | - |
| ellipsis | 超过宽度将自动省略（单行） | boolean \| { showTitle?: boolean } | false |
| filters | 表头的筛选菜单项 | ColumnFilterItem[] \| boolean | - |
| filterDropdown | 自定义筛选面板 | VNodeChild \| (props) => VNodeChild | - |
| filterIcon | 自定义 filter 图标 | VNodeChild \| (filtered) => VNodeChild | - |
| filterMode | 筛选菜单模式（树形/菜单） | `'tree' \| 'menu'` | 'menu' |
| filtered | 标识数据是否经过筛选，图标高亮 | boolean | false |
| filteredValue | 筛选的受控属性 | FilterValue \| null | - |
| filterMultiple | 是否多选 | boolean | true |
| filterSearch | 筛选菜单中是否可搜索 | boolean \| (input, record) => boolean | false |
| fixed | 列是否固定 | `'left' \| 'right'`（RTL 下 start/end） | false |
| key | 列的稳定标识，用于排序、筛选与列复用 | string | - |
| responsive | 命中任一断点时显示该列 | Breakpoint[] | - |
| rowSpan | 行合并 | number | - |
| render | 生成复杂数据的渲染，**位置参数** `(value, record, index)` | (value, record, index) => VNodeChild | - |
| showSorterTooltip | 表头排序气泡提示 | boolean \| SorterTooltipProps | true |
| sortOrder | 排序的受控属性 | `'ascend' \| 'descend' \| null` | - |
| sorter | 排序函数；true 由消费方处理排序 | boolean \| CompareFn<T> | false |
| sortDirections | 支持的排序方式（覆盖 Table 级） | SortOrder[] | `['ascend', 'descend']` |
| title | 列头显示文字 | VNodeChild \| ColumnTitle | - |
| width | 列宽度（固定列与 scroll.x 配合必填） | number \| string | - |
| children | 分组列的子列 | ColumnsType | - |
| onFilter | 本地过滤函数 | (value, record) => boolean | - |
| onFilterDropdownOpenChange | 筛选面板展开/收起的回调 | (open) => void | - |

### TableRowSelection（行选择）

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| checkStrictly | checkable 状态下父子节点是否关联 | boolean | true |
| columnTitle | 自定义选择列标题 | VNodeChild | - |
| columnWidth | 自定义选择列宽度 | number \| string | - |
| fixed | 选择列是否固定 | boolean \| `'left' \| 'right'` | - |
| getCheckboxProps | 默认的复选框属性 | (record) => Record<string, unknown> | - |
| preserveSelectedRowKeys | 数据源变更后保留上一页选中项 | boolean | - |
| renderCell | 渲染选择单元格 | (checked, record, index, originNode) => VNodeChild | - |
| selectedRowKeys | 指定选中项的 key 数组（受控） | TableKey[] | - |
| selections | 自定义选择项（`SELECTION_ALL` / `SELECTION_INVERT` / `SELECTION_NONE` 等） | SelectionItem[] \| true | - |
| type | 多选或单选 | `'checkbox' \| 'radio'` | 'checkbox' |
| onChange | 选中项发生变化时的回调 | (selectedRowKeys, selectedRows, info) => void | - |
| onSelect | 用户手动选择/取消某行的回调（含 shift 联动 info） | (record, selected, selectedRows, nativeEvent) => void | - |
| onSelectAll | 全选/取消全选的回调 | (selected, selectedRows, changeRows) => void | - |
| onSelectInvert | 反选的回调 | (selectedRowKeys) => void | - |
| onSelectNone | 清空选择的回调 | () => void | - |

### ExpandableConfig（展开）

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| childrenColumnName | 树形数据的子节点字段 | string | 'children' |
| columnTitle | 自定义展开列标题 | VNodeChild | - |
| columnWidth | 自定义展开列宽度 | number \| string | - |
| defaultExpandAllRows | 初始时展开所有行 | boolean | false |
| defaultExpandedRowKeys | 默认展开的行 | TableKey[] | - |
| expandedRowClassName | 展开行的 className | string \| (record, index, indent) => string | - |
| expandedRowKeys | 展开的行（受控） | TableKey[] | - |
| expandIconColumnIndex | 展开按钮所在列的索引 | number | - |
| fixed | 展开列的固定位置 | `'left' \| 'right' \| 'start' \| 'end'` | - |
| indentSize | 树形缩进宽度 | number | 15 |
| rowExpandable | 行是否可展开 | (record) => boolean | - |
| showExpandColumn | 是否展示展开列 | boolean | true |
| onExpand | 展开行的回调 | (expanded, record) => void | - |
| onExpandedRowsChange | 展开的行变化时的回调 | (expandedRows) => void | - |


分页根节点的 class/style 放在 pagination.class / pagination.style；原 className 配置改用 class。

### pagination（分页配置）

继承 `Pagination` 的全部 props，额外支持：

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| position | 指定分页显示的位置 | `['topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight']` | `['bottomRight']` |
| hideOnSinglePage | 只有一页时是否隐藏分页器 | boolean | false |

> `pagination: false` 时隐藏分页器；默认每页 10 条（可传 `pageSize` 覆盖）。

### TableLocale（默认文案）

| 参数 | 说明 | 类型 |
| --- | --- | --- |
| emptyText | 无数据时的文案 | VNodeChild |
| filterConfirm | 筛选「确定」按钮文案 | string |
| filterReset | 筛选「重置」按钮文案 | string |
| filterEmptyText | 筛选菜单为空的文案 | string |
| selectAll | 全选行文案 | string |
| selectInvert | 反选文案 | string |
| selectNone | 清空选择文案 | string |
| selectionAll | 全部行选择文案 | string |
| sortTitle | 排序按钮的可访问名 | string |
| expand | 展开行的可访问名 | string |
| collapse | 折叠行的可访问名 | string |
| triggerDesc | 点击降序文案 | string |
| triggerAsc | 点击升序文案 | string |
| cancelSort | 取消排序文案 | string |

## 语义化与可访问性

- 支持通过 `classNames` / `styles` 对 `root` / `section` 等语义槽位进行定制；
- 排序按钮带 `aria-sort`，展开按钮带 `aria-expanded` / `aria-label`（走 locale）；
- `caption` 提供表格的可访问名。

分页内容使用 `#paginationItemRender="{ page, type, element }"`、`#paginationTotal="{ total, range }"` 和 `#paginationSizeChanger="info"`。每个分页器接收当前作用域，支持顶部/底部及动态插槽；配置对象只放数据和业务事件，旧 itemRender/showTotal/sizeChangerRender 函数入口已移除。

## 当前主题变量

表头、排序、悬浮及筛选浮层的派生颜色跟随当前 ConfigProvider 主题，既有 Table 组件 Token 支持替换和移除，尺寸覆盖支持 0。原生根 CSS 变量优先于主题默认值；筛选 Portal 使用同一主题源。默认浅色的 40 条 CSS 变量声明保持不变。


## 基础用法 (basic)

基本使用：`columns` 定义列、`data-source` 提供数据；`bodyCell` 插槽自定义单元格渲染。

### basic.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';
import { h } from 'vue';

const columns: TableColumnsType = [
  {
    title: 'Name',
    dataIndex: 'name',
    key: 'name',
    // ⚠️ render 是 rc 口径的位置参数：(value, record, index) —— 不是对象参数。
    //    写成 ({ text }) 会把「单元格值」当对象解构，渲染出 undefined。
    render: (value: unknown) => h('a', String(value)),
  },
  { title: 'Age', dataIndex: 'age', key: 'age' },
  { title: 'Address', dataIndex: 'address', key: 'address' },
];

const data: Record<string, unknown>[] = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
  { key: '3', name: 'Joe Black', age: 28, address: 'Sydney No. 1 Lake Park' },
];
</script>

<template>
  <Table :columns="columns" :data-source="data" />
</template>
```

## 边框 (bordered)

`bordered` 展示表格内外边框。

### bordered.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Age', dataIndex: 'age' },
  { title: 'Address', dataIndex: 'address' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
];
</script>

<template>
  <Table bordered :columns="columns" :data-source="data" />
</template>
```

## 紧凑型 (size)

`size="middle" | "small"` 两种紧凑形态。

### size.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Age', dataIndex: 'age' },
  { title: 'Address', dataIndex: 'address' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
];
</script>

<template>
  <Table :columns="columns" :data-source="data" size="middle" bordered style="margin-bottom: 24px" />
  <Table :columns="columns" :data-source="data" size="small" bordered />
</template>
```

## 可展开 (expand)

`#expandedRow` 插槽 自定义展开内容；`defaultExpandAllRows` 默认全部展开。

### expand.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Age', dataIndex: 'age' },
  { title: 'Address', dataIndex: 'address' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
];
</script>

<template>
  <Table :columns="columns" :data-source="data" :expandable="{ defaultExpandAllRows: true }"><template #expandedRow="{record}">{{record.address}}</template></Table>
</template>
```

## 行选择 (selection)

`row-selection` 开启勾选列；`v-model` 形态用 `selectedRowKeys` 受控。

### selection.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableKey, TableRowSelection } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Age', dataIndex: 'age' },
  { title: 'Address', dataIndex: 'address' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
  { key: '3', name: 'Joe Black', age: 28, address: 'Sydney No. 1 Lake Park' },
];

const selectedRowKeys = ref<TableKey[]>([]);
const rowSelection = computed<TableRowSelection>(() => ({
  selectedRowKeys: selectedRowKeys.value,
  onChange: (keys: TableKey[]) => {
    selectedRowKeys.value = keys;
  },
}));
</script>

<template>
  <Table :columns="columns" :data-source="data" :row-selection="rowSelection" />
</template>
```

## 选择和操作 (row-selection-and-operation)

勾选列 + 操作列的组合：`getCheckboxProps` 按行禁用勾选，工具栏按钮读 `selectedRowKeys` 做批量操作；
选中行随数据删除同步清理，避免出现指向已删行的残留 key。

窄屏使用 `scroll.x` 保留完整列宽，横向滚动可访问操作列；键盘聚焦 Delete 时也会将按钮滚入视口。

### row-selection-and-operation.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableKey, TableRowSelection } from '@apollo-design/ui';
import { Button, Table } from '@apollo-design/ui';
import { computed, h, ref } from 'vue';

interface RecordType {
  // ⚠️ 必须显式写索引签名：见 ajax.vue 同名注释（interface 没有隐式索引签名）。
  [key: string]: unknown;
  key: string;
  name: string;
  age: number;
  address: string;
}

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Age', dataIndex: 'age' },
  { title: 'Address', dataIndex: 'address' },
  {
    title: 'Action',
    key: 'action',
    render: (_value: unknown, record: Record<string, unknown>) =>
      h(
        Button,
        { type: 'link', size: 'small', onClick: () => remove(String(record.key)) },
        () => 'Delete',
      ),
  },
];

const data = ref<RecordType[]>([
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
  { key: '3', name: 'Joe Black', age: 28, address: 'Sydney No. 1 Lake Park' },
  { key: '4', name: 'Disabled User', age: 99, address: 'Sydney No. 1 Lake Park' },
]);

const selectedRowKeys = ref<TableKey[]>([]);
const hasSelected = computed(() => selectedRowKeys.value.length > 0);

const rowSelection = computed<TableRowSelection>(() => ({
  selectedRowKeys: selectedRowKeys.value,
  onChange: (keys: TableKey[]) => {
    selectedRowKeys.value = keys;
  },
  // 第 4 行禁选（antd：`getCheckboxProps` 按行返回勾选框属性）
  getCheckboxProps: (record: Record<string, unknown>) => ({
    disabled: record.name === 'Disabled User',
  }),
}));

function remove(key: string): void {
  data.value = data.value.filter((item) => item.key !== key);
  selectedRowKeys.value = selectedRowKeys.value.filter((k) => k !== key);
}

function batchDelete(): void {
  data.value = data.value.filter((item) => !selectedRowKeys.value.includes(item.key));
  selectedRowKeys.value = [];
}
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-bottom: 16px">
      <Button type="primary" :disabled="!hasSelected" @click="batchDelete"> 批量删除 </Button>
      <span>
        {{ hasSelected ? `已选择 ${selectedRowKeys.length} 项` : '未选择' }}
      </span>
    </div>
    <Table :columns="columns" :data-source="data" :row-selection="rowSelection" :scroll="{ x: 'max-content' }" />
  </div>
</template>
```

## 单选（radio） (radio-selection)

`row-selection.type="radio"` 单选列。

### radio-selection.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableKey, TableRowSelection } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Age', dataIndex: 'age' },
  { title: 'Address', dataIndex: 'address' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
  { key: '3', name: 'Joe Black', age: 28, address: 'Sydney No. 1 Lake Park' },
];

const selectedRowKeys = ref<TableKey[]>([]);
const rowSelection = computed<TableRowSelection>(() => ({
  type: 'radio',
  selectedRowKeys: selectedRowKeys.value,
  onChange: (keys: TableKey[]) => {
    selectedRowKeys.value = keys;
  },
}));
</script>

<template>
  <Table :columns="columns" :data-source="data" :row-selection="rowSelection" />
</template>
```

## 树形数据展示 (nest)

数据带 `children` 字段即自动成为树形表格（`childrenColumnName` 可换字段名）。

### nest.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

interface DataType {
  key: string;
  name: string;
  age: number;
  children?: DataType[];
}

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Age', dataIndex: 'age', key: 'age' },
];

const data = [
  {
    key: '1',
    name: 'John Brown',
    age: 32,
    children: [
      { key: '1-1', name: 'Jim Green', age: 40 },
      {
        key: '1-2',
        name: 'Joe Black',
        age: 36,
        children: [{ key: '1-2-1', name: 'Jim Red', age: 32 }],
      },
    ],
  },
  { key: '2', name: 'Johnny Green', age: 28 },
];
</script>

<template>
  <Table :columns="columns" :data-source="data" />
</template>
```

## 排序 (sorter)

列上声明 `sorter` 即开启排序（三态循环）；`defaultSortOrder` 指定默认排序。
多重排序用 `sorter: { compare, multiple: n }`。

### sorter.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name' },
  {
    title: 'Age',
    dataIndex: 'age',
    defaultSortOrder: 'descend',
    sorter: (a: Record<string, unknown>, b: Record<string, unknown>) =>
      (a.age as number) - (b.age as number),
  },
];

const data = [
  { key: '1', name: 'John Brown', age: 32 },
  { key: '2', name: 'Jim Green', age: 42 },
  { key: '3', name: 'Joe Black', age: 28 },
];

const onChange = (_pagination: unknown, _filters: unknown, sorter: unknown) => {
  console.log('sorter params:', sorter);
};
</script>

<template>
  <Table :columns="columns" :data-source="data" @change="onChange" />
</template>
```

## 多列排序 (multiple-sorter)

`sorter` 的对象形态带 `multiple` 权重：数字越小优先级越高，多列同时排序按权重依次比较。
`onChange` 的第三个参数在多列激活时是**数组**。

### multiple-sorter.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

interface RecordType {
  // ⚠️ 必须显式写索引签名：见 ajax.vue 同名注释（interface 没有隐式索引签名）。
  [key: string]: unknown;
  key: string;
  name: string;
  chinese: number;
  math: number;
  english: number;
}

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name' },
  {
    title: 'Chinese Score',
    dataIndex: 'chinese',
    // ⭐ `multiple` 是排序权重：数字越小优先级越高
    sorter: {
      compare: (a: Record<string, unknown>, b: Record<string, unknown>) =>
        (a.chinese as number) - (b.chinese as number),
      multiple: 3,
    },
  },
  {
    title: 'Math Score',
    dataIndex: 'math',
    sorter: {
      compare: (a: Record<string, unknown>, b: Record<string, unknown>) =>
        (a.math as number) - (b.math as number),
      multiple: 2,
    },
  },
  {
    title: 'English Score',
    dataIndex: 'english',
    sorter: {
      compare: (a: Record<string, unknown>, b: Record<string, unknown>) =>
        (a.english as number) - (b.english as number),
      multiple: 1,
    },
  },
];

const data: RecordType[] = [
  { key: '1', name: 'John Brown', chinese: 98, math: 60, english: 70 },
  { key: '2', name: 'Jim Green', chinese: 98, math: 66, english: 89 },
  { key: '3', name: 'Joe Black', chinese: 98, math: 90, english: 70 },
  { key: '4', name: 'Jim Red', chinese: 88, math: 99, english: 89 },
];

const onChange = (_pagination: unknown, _filters: unknown, sorter: unknown) => {
  console.log('sorter params:', sorter);
};
</script>

<template>
  <Table :columns="columns" :data-source="data" @change="onChange" />
</template>
```

## 筛选 (filter)

列上声明 `filters` + `onFilter` 开启筛选下拉；`filterMultiple` 控制多选/单选；
`filteredValue` 受控。

### filter.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

const columns: TableColumnsType = [
  {
    title: 'Name',
    dataIndex: 'name',
    filters: [
      { text: 'Joe', value: 'Joe' },
      { text: 'John', value: 'John' },
    ],
    onFilter: (value: unknown, record: Record<string, unknown>) =>
      (record.name as string).includes(value as string),
  },
  {
    title: 'Age',
    dataIndex: 'age',
    sorter: (a: Record<string, unknown>, b: Record<string, unknown>) =>
      (a.age as number) - (b.age as number),
  },
  { title: 'Address', dataIndex: 'address' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
  { key: '3', name: 'Joe Black', age: 28, address: 'Sydney No. 1 Lake Park' },
];

const onChange = (
  _pagination: unknown,
  filters: unknown,
  _sorter: unknown,
  { currentDataSource }: { currentDataSource: unknown[] },
) => {
  console.log('filters:', filters, 'data:', currentDataSource);
};
</script>

<template>
  <Table :columns="columns" :data-source="data" @change="onChange" />
</template>
```

## 筛选可搜索 (filter-search)

列上 `filterSearch` 打开筛选下拉里的搜索框：`true` 按 `value` 直接匹配，
函数形态可自定义比对逻辑（第二参是筛选项 `{ text, value }`）。

### filter-search.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

const columns: TableColumnsType = [
  {
    title: 'Name',
    dataIndex: 'name',
    // ⭐ 项多时给个搜索框；`filterSearch: true` 直接按 value 过滤
    filters: [
      { text: 'Joe', value: 'Joe' },
      { text: 'John', value: 'John' },
      { text: 'Jim', value: 'Jim' },
    ],
    filterSearch: true,
    onFilter: (value: unknown, record: Record<string, unknown>) =>
      (record.name as string).includes(value as string),
  },
  {
    title: 'Address',
    dataIndex: 'address',
    filters: [
      { text: 'London', value: 'London' },
      { text: 'New York', value: 'New York' },
      { text: 'Sydney', value: 'Sydney' },
    ],
    // 函数形态：自定义匹配字段（这里按城市名前缀匹配）
    filterSearch: (input: string, record: { value?: unknown; text?: unknown }) =>
      String(record.value ?? '')
        .toLowerCase()
        .includes(input.toLowerCase()),
    onFilter: (value: unknown, record: Record<string, unknown>) =>
      (record.address as string).includes(value as string),
  },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
  { key: '3', name: 'Joe Black', age: 28, address: 'Sydney No. 1 Lake Park' },
  { key: '4', name: 'Jim Red', age: 32, address: 'London No. 2 Lake Park' },
];
</script>

<template>
  <Table :columns="columns" :data-source="data" />
</template>
```

## 自定义筛选菜单 (custom-filter-panel)

列上 `filterDropdown` 完全接管筛选面板（拿到 `setSelectedKeys / confirm / clearFilters` 三件套），
配合 `onFilter` 做本地过滤、`filterIcon` 自定义漏斗图标的高亮态。

### custom-filter-panel.vue

```vue
<script setup lang="ts">
// ⚠️ table 的内部类型在根出口统一加 `Table` 前缀（`FilterDropdownProps`
//    → `TableFilterDropdownProps`），别照着 table/index.ts 的内部名直接引。
import type { TableColumnsType, TableFilterDropdownProps, TableKey } from '@apollo-design/ui';
import { Button, Input, Table } from '@apollo-design/ui';
import { h, ref } from 'vue';

const searchInput = ref('');

const columns: TableColumnsType = [
  {
    title: 'Name',
    dataIndex: 'name',
    // ⭐ 自定义筛选面板：`filterDropdown` 拿到 setSelectedKeys / confirm / clearFilters
    filterDropdown: (props: TableFilterDropdownProps) =>
      h('div', { style: { padding: '8px' } }, [
        h(Input, {
          value: searchInput.value,
          placeholder: 'Search name',
          style: { width: '188px', marginBottom: '8px', display: 'block' },
          'onUpdate:value': (v: string) => {
            searchInput.value = v;
          },
          onPressEnter: () => {
            props.setSelectedKeys(searchInput.value ? [searchInput.value] : []);
            props.confirm({ closeDropdown: true });
          },
        }),
        h(
          Button,
          {
            type: 'primary',
            size: 'small',
            style: { width: '90px', marginRight: '8px' },
            onClick: () => {
              props.setSelectedKeys(searchInput.value ? [searchInput.value] : []);
              props.confirm({ closeDropdown: true });
            },
          },
          { default: () => 'Search' },
        ),
        h(
          Button,
          {
            size: 'small',
            style: { width: '90px' },
            onClick: () => {
              searchInput.value = '';
              props.clearFilters?.({ confirm: true, closeDropdown: true });
            },
          },
          { default: () => 'Reset' },
        ),
      ]),
    // 漏斗图标的高亮态由「是否有筛选值」决定
    onFilter: (value: unknown, record: Record<string, unknown>) =>
      (record.name as string).toLowerCase().includes(String(value).toLowerCase()),
    filterIcon: (filtered: boolean) =>
      h('span', { style: { color: filtered ? '#1677ff' : undefined } }, '🔍'),
  },
  { title: 'Age', dataIndex: 'age' },
  { title: 'Address', dataIndex: 'address' },
];

const data: Record<string, unknown>[] = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
  { key: '3', name: 'Joe Black', age: 28, address: 'Sydney No. 1 Lake Park' },
];

const onChange = (_p: unknown, filters: unknown) => {
  console.log('filters:', filters, 'keys:', (filters as Record<string, TableKey[]>)?.name);
};
</script>

<template>
  <Table :columns="columns" :data-source="data" @change="onChange" />
</template>
```

## 固定表头 (fixed-header)

`scroll.y` 给表体一个固定高度 ⇒ 表头吸顶、表体独立滚动。列宽建议显式声明，
否则表头与表体的列宽会各自按内容计算、滚动时对不齐。

### fixed-header.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', width: 150 },
  { title: 'Age', dataIndex: 'age', width: 80 },
  { title: 'Address', dataIndex: 'address' },
];

const data: Record<string, unknown>[] = [];
for (let i = 0; i < 20; i += 1) {
  data.push({
    key: String(i),
    name: `Edward King ${i}`,
    age: 32,
    address: `London, Park Lane no. ${i}`,
  });
}
</script>

<template>
  <!-- ⭐ scroll.y 给表体一个固定高度 ⇒ 表头吸顶、表体独立滚动 -->
  <Table :columns="columns" :data-source="data" :scroll="{ y: 240 }" :pagination="false" />
</template>
```

## 固定列 (fixed-columns)

列声明 `fixed: 'left' | 'right'` 固定列；横向内容超出时（`scroll.x`）固定列吸边并带阴影。

### fixed-columns.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name', width: 120, fixed: 'left' },
  { title: 'Age', dataIndex: 'age', key: 'age', width: 100 },
  { title: 'Column 1', dataIndex: 'address', key: 'address1', width: 150 },
  { title: 'Column 2', dataIndex: 'address', key: 'address2', width: 150 },
  { title: 'Column 3', dataIndex: 'address', key: 'address3', width: 150 },
  { title: 'Address', dataIndex: 'address', key: 'address', width: 120, fixed: 'right' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
];
</script>

<template>
  <Table :columns="columns" :data-source="data" :scroll="{ x: 790 }" style="width: 480px; max-width: 100%" />
</template>
```

## 固定头和列 (fixed-columns-header)

`scroll` 同时给 `x` 与 `y`：横向由 `fixed: 'left' | 'right'` 的列吸边，纵向表头吸顶。
固定列与滚动列的交界处会自动带阴影。

### fixed-columns-header.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';
import { h } from 'vue';

const columns: TableColumnsType = [
  { title: 'Full Name', dataIndex: 'name', width: 150, fixed: 'left' },
  { title: 'Age', dataIndex: 'age', width: 100, fixed: 'left' },
  { title: 'Column 1', dataIndex: 'address', width: 200 },
  { title: 'Column 2', dataIndex: 'address', width: 200 },
  { title: 'Column 3', dataIndex: 'address', width: 200 },
  { title: 'Column 4', dataIndex: 'address', width: 200 },
  { title: 'Column 5', dataIndex: 'address', width: 200 },
  { title: 'Column 6', dataIndex: 'address', width: 200 },
  {
    title: 'Action',
    key: 'action',
    width: 120,
    fixed: 'right',
    render: () => h('a', 'action'),
  },
];

const data: Record<string, unknown>[] = [];
for (let i = 0; i < 20; i += 1) {
  data.push({
    key: String(i),
    name: `Edward ${i}`,
    age: 32,
    address: `London Park no. ${i}`,
  });
}
</script>

<template>
  <!-- ⭐ 同时给 x 与 y：横向固定列吸边、纵向表头吸顶 -->
  <Table
    :columns="columns"
    :data-source="data"
    :scroll="{ x: 1500, y: 240 }"
    :pagination="false"
  />
</template>
```

## 表头分组 (grouping-columns)

列的 `children` 即多级表头（可嵌套任意层）；带 `children` 的列只做分组、不渲染单元格。
分组表头同样支持 `fixed` 与 `filters / sorter`。

### grouping-columns.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

// ⭐ 列的 `children` 即多级表头：有 children 的列不渲染单元格，只做分组
const columns: TableColumnsType = [
  {
    title: 'Name',
    dataIndex: 'name',
    key: 'name',
    width: 100,
    fixed: 'left',
    filters: [
      { text: 'John', value: 'John' },
      { text: 'Joe', value: 'Joe' },
    ],
    onFilter: (value: unknown, record: Record<string, unknown>) =>
      (record.name as string).includes(value as string),
  },
  {
    title: 'Other',
    children: [
      { title: 'Age', dataIndex: 'age', key: 'age', width: 150, sorter: true },
      {
        title: 'Address',
        children: [
          { title: 'Street', dataIndex: 'street', key: 'street', width: 150 },
          {
            title: 'Block',
            children: [
              { title: 'Building', dataIndex: 'building', key: 'building', width: 100 },
              { title: 'Door No.', dataIndex: 'number', key: 'number', width: 100 },
            ],
          },
        ],
      },
    ],
  },
  {
    title: 'Company',
    children: [
      { title: 'Company Address', dataIndex: 'companyAddress', key: 'companyAddress' },
      { title: 'Company Name', dataIndex: 'companyName', key: 'companyName' },
    ],
  },
  { title: 'Gender', dataIndex: 'gender', key: 'gender', width: 80, fixed: 'right' },
];

const data: Record<string, unknown>[] = [];
for (let i = 0; i < 10; i += 1) {
  data.push({
    key: String(i),
    name: i % 2 === 0 ? 'John Brown' : 'Joe Black',
    age: i + 20,
    street: 'Lake Park',
    building: 'C',
    number: 2035,
    companyAddress: 'Lake Street 42',
    companyName: 'SoftLake Co',
    gender: 'M',
  });
}
</script>

<template>
  <Table
    :columns="columns"
    :data-source="data"
    :scroll="{ x: 'max-content' }"
    bordered
    :pagination="false"
  />
</template>
```

## 表格行/列合并 (colspan-rowspan)

单元格合并靠列的 `onCell`：返回 `{ colSpan }` 跨列、`{ rowSpan }` 跨行。
⚠️ 被跨掉的格子必须显式返回 `0`，否则后面的列会整体错位 —— 合并是「按格算」而不是「按列算」。

第二行的 Age 跨两列，覆盖返回 `colSpan: 0` 的 Home phone；Name 分别跨前三行和后两行，后两行的 Home phone 也纵向合并。

### colspan-rowspan.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

/**
 * ⭐ 单元格合并靠列的 `onCell`：返回 `{ colSpan }` 跨列、`{ rowSpan }` 跨行。
 * 被跨掉的格子要返回 `{ colSpan: 0 }` / `{ rowSpan: 0 }`，否则后面的列会整体错位。
 */
const sharedOnCell = (_record: Record<string, unknown>, rowIndex: number) => {
  if (rowIndex === 1) return { colSpan: 0 };
  if (rowIndex === 3) return { rowSpan: 2 };
  if (rowIndex === 4) return { rowSpan: 0 };
  return {};
};

const columns: TableColumnsType = [
  {
    title: 'Name',
    dataIndex: 'name',
    onCell: (_r: unknown, index: number) => ({
      rowSpan: index === 0 ? 3 : index === 3 ? 2 : 0,
    }),
  },
  {
    title: 'Age',
    dataIndex: 'age',
    // 第二行跨 Age + Home phone，与 sharedOnCell 的 colSpan: 0 成对。
    onCell: (_record, rowIndex) => ({ colSpan: rowIndex === 1 ? 2 : 1 }),
  },
  { title: 'Home phone', dataIndex: 'tel', onCell: sharedOnCell },
  { title: 'Phone', dataIndex: 'phone' },
  { title: 'Address', dataIndex: 'address' },
];

const data: Record<string, unknown>[] = [
  {
    key: '1',
    name: 'John Brown',
    age: 32,
    tel: '0571-22098909',
    phone: 18889898989,
    address: 'New York No. 1 Lake Park',
  },
  {
    key: '2',
    name: 'Jim Green',
    age: 42,
    tel: '0571-22098333',
    phone: 18889898888,
    address: 'London No. 1 Lake Park',
  },
  {
    key: '3',
    name: 'Joe Black',
    age: 32,
    tel: '0575-22098909',
    phone: 18900010002,
    address: 'Sydney No. 1 Lake Park',
  },
  {
    key: '4',
    name: 'Jim Red',
    age: 18,
    tel: '0575-22098909',
    phone: 18900010002,
    address: 'London No. 2 Lake Park',
  },
  {
    key: '5',
    name: 'Jake White',
    age: 18,
    tel: '0575-22098909',
    phone: 18900010002,
    address: 'Dublin No. 2 Lake Park',
  },
];
</script>

<template>
  <Table :columns="columns" :data-source="data" bordered :pagination="false" />
</template>
```

## 汇总行 (summary)

使用 `#summary` 插槽与 `Summary`、`TableSummaryRow`、`TableSummaryCell` 命名组件渲染表尾汇总，通过 `colSpan` 合并列。命名组件也适用于模板自动引入。

### summary.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Summary, Table, TableSummaryCell, TableSummaryRow } from '@apollo-design/ui';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Age', dataIndex: 'age' },
  { title: 'Address', dataIndex: 'address' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
  { key: '3', name: 'Joe Black', age: 28, address: 'Sydney No. 1 Lake Park' },
];

const total = data.reduce((acc, d) => acc + d.age, 0);
</script>

<template>
  <Table :columns="columns" :data-source="data" bordered>
    <template #summary>
      <Summary>
        <TableSummaryRow>
          <TableSummaryCell :index="0" :col-span="2">Total</TableSummaryCell>
          <TableSummaryCell :index="2">{{ total }}</TableSummaryCell>
        </TableSummaryRow>
      </Summary>
    </template>
  </Table>
</template>
```

## 自定义空状态 (custom-empty)

`emptyText` 覆盖空数据时的占位内容（VNode 或返回 VNode 的函数）。
需要跟页面其它空态保持一致时用它，而不是改全局 locale。

### custom-empty.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Age', dataIndex: 'age' },
  { title: 'Address', dataIndex: 'address' },
];
</script>

<template>
  <Table :columns="columns" :data-source="[]" bordered>
    <template #emptyText><div style="padding:24px;text-align:center"><div style="font-size:32px">🗂️</div><div style="margin-top:8px;color:var(--apollo-color-text-secondary)">暂无数据</div></div></template>
  </Table>
</template>
```

## 超出省略 (ellipsis)

列上 `ellipsis` 让超出列宽的内容单行省略。⚠️ 它依赖确定的列宽 ——
不给 `width` 时浏览器无从判断「超出」，省略不会生效。

### ellipsis.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

// ⭐ ellipsis 需要配合固定列宽：宽度不定时浏览器无从判断「超出」
const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', width: 120, ellipsis: true },
  { title: 'Age', dataIndex: 'age', width: 80, align: 'center' },
  {
    title: 'Address',
    dataIndex: 'address',
    width: 260,
    ellipsis: true,
  },
];

const data: Record<string, unknown>[] = [
  {
    key: '1',
    name: 'John Brown',
    age: 32,
    address: 'New York No. 1 Lake Park, New York No. 1 Lake Park, New York No. 1 Lake Park',
  },
  {
    key: '2',
    name: 'Jim Green',
    age: 42,
    address: 'London No. 1 Lake Park, London No. 1 Lake Park, London No. 1 Lake Park',
  },
  {
    key: '3',
    name: 'Joe Black',
    age: 28,
    address: 'Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park',
  },
];
</script>

<template>
  <Table :columns="columns" :data-source="data" :pagination="false" />
</template>
```

## 远程加载数据 (ajax)

服务端分页的标准形态：`pagination` 受控（`current / pageSize / total` 都来自响应），
翻页在 `change` 里重新拉数据，`loading` 覆盖请求期。
示例用一个本地假接口代替真实请求 —— 保持离线可跑、结果确定。

### ajax.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TablePaginationConfig } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';
import { onMounted, ref, shallowRef } from 'vue';

interface RecordType {
  key: string;
  name: string;
  gender: 'male' | 'female';
  email: string;
}

const columns: TableColumnsType<RecordType> = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Gender', dataIndex: 'gender' },
  { title: 'Email', dataIndex: 'email' },
];

const data = ref<RecordType[]>([]);
const loading = ref(false);
const pagination = shallowRef<TablePaginationConfig>({ current: 1, pageSize: 10, total: 0 });

/** 用一个本地的「假接口」代替真实请求 —— 示例保持离线可跑、结果确定。 */
const DB: RecordType[] = Array.from({ length: 46 }, (_unused, i) => ({
  key: String(i),
  name: i % 2 === 0 ? `Edward King ${i}` : `Lucy White ${i}`,
  gender: i % 2 === 0 ? 'male' : 'female',
  email: `user${i}@example.com`,
}));

async function fakeFetch(params: {
  current?: number;
  pageSize?: number;
}): Promise<{ results: RecordType[]; total: number }> {
  const current = params.current ?? 1;
  const pageSize = params.pageSize ?? 10;
  const start = (current - 1) * pageSize;
  return { results: DB.slice(start, start + pageSize), total: DB.length };
}

async function fetchData(page = pagination.value): Promise<void> {
  loading.value = true;
  try {
    const res = await fakeFetch({ current: page.current, pageSize: page.pageSize });
    data.value = res.results;
    // Pagination is replaced atomically; only the current page request belongs to this service.
    pagination.value = {
      current: page.current ?? 1,
      pageSize: page.pageSize ?? 10,
      total: res.total,
    };
  } finally {
    loading.value = false;
  }
}

// ⭐ 服务端分页：`pagination` 受控 + 在 change 里重新拉数据
async function onChange(next: TablePaginationConfig): Promise<void> {
  // The data service consumes only the requested page and page size.
  await fetchData({
    current: next.current ?? 1,
    pageSize: next.pageSize ?? pagination.value.pageSize ?? 10,
  });
}

onMounted(() => {
  void fetchData();
});
</script>

<template>
  <Table
    :columns="columns"
    :data-source="data"
    :loading="loading"
    :pagination="pagination"
    @change="onChange"
  />
</template>
```

## 粘性头部 (sticky)

`sticky` 让表头随页面滚动吸顶（区别于 `scroll.y` —— 那个是表体自己滚、表头不动）。
`sticky` 传对象时可指定 `{ offsetHeader, offsetScroll, getContainer }`。

### sticky.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';
import { h } from 'vue';

const columns: TableColumnsType = [
  { title: 'Full Name', dataIndex: 'name', width: 150 },
  { title: 'Age', dataIndex: 'age', width: 80 },
  { title: 'Column 1', dataIndex: 'address', width: 200 },
  { title: 'Column 2', dataIndex: 'address', width: 200 },
  { title: 'Column 3', dataIndex: 'address', width: 200 },
  {
    title: 'Action',
    key: 'action',
    width: 120,
    render: () => h('a', 'action'),
  },
];

const data: Record<string, unknown>[] = [];
for (let i = 0; i < 20; i += 1) {
  data.push({
    key: String(i),
    name: `Edward ${i}`,
    age: 32,
    address: `London Park no. ${i}`,
  });
}
</script>

<template>
  <!-- ⭐ sticky：表格随页面滚动时，表头吸在容器顶部（这里是窗口顶部偏移 0） -->
  <Table
    :columns="columns"
    :data-source="data"
    :scroll="{ x: 1300 }"
    sticky
    :pagination="false"
  />
</template>
```

## 虚拟滚动 (virtual-list)

`virtual` 开启虚拟滚动（大表格场景）：表体交给 `@apollo-design/virtual-list`，只渲染视口内的行。
`scroll.y` 给视口高度、`scroll.x` 给内容宽度 —— **virtual 下二者必须是数值**（否则按 1 / 500 兜底并告警）。

### virtual-list.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Table } from '@apollo-design/ui';

/**
 * 对齐 antd `components/table/demo/virtual-list.tsx` 的**静态形态**：
 * 固定列（左 3 / 右 1）+ rowSpan/colSpan + 横向 2000px + 纵向 400px 视口。
 * 交互开关（bordered / fixed / expandable / empty / count）不进静态帧。
 *
 * ⚠️ 数据用 `Record<string, unknown>`（不是自定义 interface）—— 本仓 `TableColumnsType`
 * 的 `onCell` 签名要求 `Record<string, unknown>`，自定义 interface 缺索引签名会不兼容。
 */
const columns: TableColumnsType = [
  { title: 'ID', dataIndex: 'id', width: 100, fixed: 'left' },
  { title: 'FistName', dataIndex: 'firstName', width: 120, fixed: 'left' },
  { title: 'LastName', dataIndex: 'lastName', width: 120, fixed: 'left' },
  {
    title: 'Group',
    width: 120,
    render: (_value: unknown, record: Record<string, unknown>) =>
      `Group ${Math.floor(Number(record.id) / 4)}`,
    onCell: (record: Record<string, unknown>) => ({ rowSpan: Number(record.id) % 4 === 0 ? 4 : 0 }),
  },
  {
    title: 'Age',
    dataIndex: 'age',
    width: 100,
    onCell: (record: Record<string, unknown>) => ({ colSpan: Number(record.id) % 4 === 0 ? 2 : 1 }),
  },
  {
    title: 'Address 1',
    dataIndex: 'address1',
    onCell: (record: Record<string, unknown>) => ({ colSpan: Number(record.id) % 4 === 0 ? 0 : 1 }),
  },
  { title: 'Address 2', dataIndex: 'address2' },
  { title: 'Address 3', dataIndex: 'address3' },
  { title: 'Action', width: 150, fixed: 'right', render: () => 'Action' },
];

const data: Record<string, unknown>[] = Array.from({ length: 200 }).map((_, index) => ({
  id: index,
  firstName: `First_${index.toString(16)}`,
  lastName: `Last_${index.toString(16)}`,
  age: 25 + (index % 10),
  address1: `New York No. ${index} Lake Park`,
  address2: `London No. ${index} Lake Park`,
  address3: `Sydney No. ${index} Lake Park`,
}));
</script>

<template>
  <Table
    bordered
    virtual
    :columns="columns"
    :scroll="{ x: 2000, y: 400 }"
    :data-source="data"
    row-key="id"
    :pagination="false"
  />
</template>
```

## 行与列的顺序调整 (drag-reorder)

通过已有 `onRow`、列 `onHeaderCell` 接入浏览器原生拖放事件，拖动后更新受控 `dataSource` / `columns` 顺序，不依赖 React 或第三方拖拽运行时。行与列分别拖放；按钮提供可用键盘操作的同等调整方式，并支持重置。这是消费端组合示例，Table 没有新增内建拖拽 prop。

### drag-reorder.vue

```vue
<script setup lang="ts">
import { Button, Flex, Select, Table, type TableColumnsType } from '@apollo-design/ui';
import { computed, ref } from 'vue';

type Row = { key: string; name: string; age: number; city: string };
type Axis = 'row' | 'column';
const rows: Row[] = [
  { key: 'a', name: 'Alice', age: 28, city: 'Shanghai' },
  { key: 'b', name: 'Bob', age: 32, city: 'Beijing' },
  { key: 'c', name: 'Carol', age: 25, city: 'Hangzhou' },
];
const definitions = [
  { key: 'name', dataIndex: 'name', title: 'Name' },
  { key: 'age', dataIndex: 'age', title: 'Age' },
  { key: 'city', dataIndex: 'city', title: 'City' },
] satisfies TableColumnsType;
const rowOrder = ref(['a', 'b', 'c']);
const columnOrder = ref(['name', 'age', 'city']);
const selectedRow = ref('a');
const selectedColumn = ref('name');
const dragging = ref<{ axis: Axis; key: string } | null>(null);
const dataSource = computed(() =>
  rowOrder.value.flatMap((key) => rows.filter((row) => row.key === key)),
);

function move(axis: Axis, key: string, target: string): void {
  const order = axis === 'row' ? rowOrder : columnOrder;
  const from = order.value.indexOf(key);
  const to = order.value.indexOf(target);
  if (from < 0 || to < 0 || from === to) return;
  const next = order.value.filter((value) => value !== key);
  next.splice(to, 0, key);
  order.value = next;
}

function moveSelected(axis: Axis, offset: number): void {
  const order = axis === 'row' ? rowOrder.value : columnOrder.value;
  const key = axis === 'row' ? selectedRow.value : selectedColumn.value;
  const target = order[order.indexOf(key) + offset];
  if (target) move(axis, key, target);
}

function dragAttrs(axis: Axis, key: string): Record<string, unknown> {
  return {
    draggable: true,
    'data-drag-key': `${axis}:${key}`,
    onDragstart: (event: DragEvent) => {
      dragging.value = { axis, key };
      if (event.dataTransfer) {
        event.dataTransfer.effectAllowed = 'move';
        event.dataTransfer.setData('text/plain', `${axis}:${key}`);
      }
    },
    onDragover: (event: DragEvent) => {
      if (dragging.value?.axis === axis) event.preventDefault();
    },
    onDrop: (event: DragEvent) => {
      if (dragging.value?.axis !== axis) return;
      event.preventDefault();
      move(axis, dragging.value.key, key);
      dragging.value = null;
    },
    onDragend: () => {
      dragging.value = null;
    },
  };
}

const columns = computed<TableColumnsType>(() =>
  columnOrder.value.flatMap((key) => {
    const column = definitions.find((entry) => entry.key === key);
    return column ? [{ ...column, onHeaderCell: () => dragAttrs('column', key) }] : [];
  }),
);
const onRow = (row: Record<string, unknown>) =>
  typeof row.key === 'string' ? dragAttrs('row', row.key) : {};
const reset = () => {
  rowOrder.value = ['a', 'b', 'c'];
  columnOrder.value = ['name', 'age', 'city'];
  dragging.value = null;
};
</script>

<template>
  <Flex vertical gap="small">
    <p>拖动行或列头调整顺序，也可选择条目后使用按钮。Drag rows or headers, or use the controls.</p>
    <Flex wrap gap="small" align="center">
      <label>Row <Select v-model:value="selectedRow" aria-label="Row to move" :options="rows.map(row => ({ value: row.key, label: row.name }))" style="width: 120px" /></label>
      <Button :disabled="rowOrder.indexOf(selectedRow) === 0" @click="moveSelected('row', -1)">Move row up</Button>
      <Button :disabled="rowOrder.indexOf(selectedRow) === rowOrder.length - 1" @click="moveSelected('row', 1)">Move row down</Button>
      <label>Column <Select v-model:value="selectedColumn" aria-label="Column to move" :options="definitions.map(column => ({ value: column.key, label: column.title }))" style="width: 120px" /></label>
      <Button :disabled="columnOrder.indexOf(selectedColumn) === 0" @click="moveSelected('column', -1)">Move column left</Button>
      <Button :disabled="columnOrder.indexOf(selectedColumn) === columnOrder.length - 1" @click="moveSelected('column', 1)">Move column right</Button>
      <Button @click="reset">Reset order</Button>
    </Flex>
    <Table :columns="columns" :data-source="dataSource" :on-row="onRow" :pagination="false" row-key="key" />
    <output aria-live="polite">Rows: {{ rowOrder.join(',') }}; Columns: {{ columnOrder.join(',') }}</output>
  </Flex>
</template>
```

## 列默认值 (column-defaults)

使用 `column` 为全部列提供公共默认值，切换 `align` 可观察它只作用于未显式声明对齐方式的列。

### column-defaults.vue

```vue
<script setup lang="ts">
import type { TableColumnInterface, TableColumnsType } from '@apollo-design/ui';
import { Select, Space, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

type Align = 'left' | 'center' | 'right';

const align = ref<Align>('center');

const alignOptions: { value: Align; label: string }[] = [
  { value: 'left', label: 'left' },
  { value: 'center', label: 'center' },
  { value: 'right', label: 'right' },
];

const columns: TableColumnsType = [
  {
    title: 'Name（显式左对齐）',
    dataIndex: 'name',
    key: 'name',
    // 列自身配置优先于 column 提供的公共默认值
    align: 'left',
  },
  { title: 'Age', dataIndex: 'age', key: 'age' },
  { title: 'City', dataIndex: 'city', key: 'city' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, city: 'New York' },
  { key: '2', name: 'Jim Green', age: 42, city: 'London' },
  { key: '3', name: 'Joe Black', age: 28, city: 'Sydney' },
  { key: '4', name: 'Jim Red', age: 32, city: 'London' },
];

/** `column` 提供所有列的公共默认值；列自身的 align 会覆盖它。 */
const defaultColumn = computed<Partial<TableColumnInterface>>(() => ({
  align: align.value,
}));

function onAlignChange(value: unknown): void {
  align.value = value as Align;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>column.align</span>
      <Select
        aria-label="列对齐方式"
        :value="align"
        :options="alignOptions"
        style="width: 120px"
        @change="onAlignChange"
      />
      <Tag color="blue">{{ align }}</Tag>
      <Tag>Name 列显式 align="left"</Tag>
    </Space>

    <Table :columns="columns" :data-source="data" :column="defaultColumn" />
  </div>
</template>
```

## 可编辑单元格 (editable-cell)

在列 `render` 中渲染 Input 与 InputNumber，直接修改本地数据并统计编辑次数，支持一键重置。

### editable-cell.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Button, Input, InputNumber, Space, Table, Tag } from '@apollo-design/ui';
import { h, ref } from 'vue';

interface EditableRow {
  [key: string]: unknown;
  key: string;
  name: string;
  age: number;
  role: string;
}

const createRows = (): EditableRow[] => [
  { key: '1', name: 'John Brown', age: 32, role: '前端工程师' },
  { key: '2', name: 'Jim Green', age: 42, role: '后端工程师' },
  { key: '3', name: 'Joe Black', age: 28, role: '设计师' },
];

const data = ref<EditableRow[]>(createRows());
const editCount = ref(0);
const lastEdit = ref('尚未编辑');

function updateField(row: EditableRow, field: 'name' | 'age', value: string | number): void {
  if (field === 'age') {
    const nextAge = Number(value);
    if (!Number.isFinite(nextAge)) return;
    row.age = nextAge;
  } else {
    row.name = String(value);
  }
  editCount.value += 1;
  lastEdit.value = `${row.name} 的 ${field} 更新为 ${String(value)}`;
}

const columns: TableColumnsType = [
  {
    title: 'Name',
    dataIndex: 'name',
    key: 'name',
    render: (_value: unknown, record: Record<string, unknown>) =>
      h(Input, {
        size: 'small',
        'aria-label': `姓名（第 ${String(record.key)} 行）`,
        value: record.name as string,
        'onUpdate:value': (value: string) =>
          updateField(record as unknown as EditableRow, 'name', value),
      }),
  },
  {
    title: 'Age',
    dataIndex: 'age',
    key: 'age',
    width: 120,
    render: (_value: unknown, record: Record<string, unknown>) =>
      h(InputNumber, {
        size: 'small',
        'aria-label': `年龄（第 ${String(record.key)} 行）`,
        value: record.age as number,
        min: 1,
        max: 120,
        style: { width: '88px' },
        'onUpdate:value': (value: string | number | null) => {
          if (value !== null) updateField(record as unknown as EditableRow, 'age', value);
        },
      }),
  },
  { title: 'Role', dataIndex: 'role', key: 'role' },
];

function resetRows(): void {
  data.value = createRows();
  editCount.value = 0;
  lastEdit.value = '已重置，尚未编辑';
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Button @click="resetRows">重置数据</Button>
      <Tag color="blue">编辑次数：{{ editCount }}</Tag>
      <Tag>{{ lastEdit }}</Tag>
    </Space>

    <Table :columns="columns" :data-source="data" :pagination="false" />
  </div>
</template>
```

## 树形数据 (tree-data)

通过 `childrenColumnName="subRows"` 指定树形字段，并用 `expandable.expandedRowKeys` 受控展开，按钮可全部展开或收起。

### tree-data.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableExpandableConfig, TableKey } from '@apollo-design/ui';
import { Button, Space, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

interface TreeRow {
  [key: string]: unknown;
  key: string;
  name: string;
  role: string;
  subRows?: TreeRow[];
}

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Role', dataIndex: 'role', key: 'role' },
];

const data: TreeRow[] = [
  {
    key: '1',
    name: 'Engineering',
    role: '部门',
    subRows: [
      { key: '1-1', name: 'Alice', role: '前端工程师' },
      { key: '1-2', name: 'Bob', role: '后端工程师' },
    ],
  },
  {
    key: '2',
    name: 'Design',
    role: '部门',
    subRows: [
      { key: '2-1', name: 'Carol', role: '视觉设计师' },
      { key: '2-2', name: 'David', role: '交互设计师' },
    ],
  },
];

const allKeys: TableKey[] = ['1', '2'];
const expandedRowKeys = ref<TableKey[]>(['1']);

const expandable = computed<TableExpandableConfig>(() => ({
  expandedRowKeys: expandedRowKeys.value,
  onExpandedRowsChange: (keys: TableKey[]) => {
    expandedRowKeys.value = keys;
  },
}));

function expandAll(): void {
  expandedRowKeys.value = [...allKeys];
}

function collapseAll(): void {
  expandedRowKeys.value = [];
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Button type="primary" @click="expandAll">全部展开</Button>
      <Button @click="collapseAll">全部收起</Button>
      <Tag color="blue">已展开 {{ expandedRowKeys.length }} 个节点</Tag>
    </Space>

    <Table
      :columns="columns"
      :data-source="data"
      children-column-name="subRows"
      :expandable="expandable"
      :pagination="false"
    />
  </div>
</template>
```

## 树形筛选搜索 (filter-search-tree)

结合 `filterMode="tree"`、嵌套 `filters` 与 `filterSearch` 搜索分类，`@change` 会实时展示当前选中的筛选值。

### filter-search-tree.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableProps } from '@apollo-design/ui';
import { Space, Table, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  {
    title: 'Department',
    dataIndex: 'department',
    key: 'department',
    // 树形筛选菜单 + 可搜索
    filterMode: 'tree',
    filterSearch: true,
    filters: [
      {
        text: 'Engineering',
        value: 'engineering',
        children: [
          { text: 'Frontend', value: 'frontend' },
          { text: 'Backend', value: 'backend' },
        ],
      },
      {
        text: 'Design',
        value: 'design',
        children: [
          { text: 'Visual', value: 'visual' },
          { text: 'Interaction', value: 'interaction' },
        ],
      },
      { text: 'Marketing', value: 'marketing' },
    ],
    onFilter: (value: unknown, record: Record<string, unknown>) =>
      record.department === value || record.team === value,
  },
  { title: 'Team', dataIndex: 'team', key: 'team' },
];

const data = [
  { key: '1', name: 'Alice', department: 'engineering', team: 'frontend' },
  { key: '2', name: 'Bob', department: 'engineering', team: 'backend' },
  { key: '3', name: 'Carol', department: 'design', team: 'visual' },
  { key: '4', name: 'David', department: 'design', team: 'interaction' },
  { key: '5', name: 'Eve', department: 'marketing', team: 'growth' },
];

const activeFilters = ref<string[]>([]);

const onTableChange: TableProps['onChange'] = (_pagination, filters) => {
  activeFilters.value = (filters.department ?? []).map((value) => String(value));
};
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>部门筛选：</span>
      <Tag color="blue">
        {{ activeFilters.length ? activeFilters.join('、') : '未筛选' }}
      </Tag>
      <Tag>打开表头筛选菜单可搜索分类</Tag>
    </Space>

    <Table :columns="columns" :data-source="data" @change="onTableChange" />
  </div>
</template>
```

## 容器内吸顶表头 (sticky-container)

在固定高度的滚动容器内使用 `sticky`，滚动时表头吸附在容器顶部，按钮可快速验证吸顶效果。

### sticky-container.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Button, Space, Table, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

interface RowData {
  [key: string]: unknown;
  key: string;
  name: string;
  age: number;
  address: string;
}

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Age', dataIndex: 'age', key: 'age', width: 100 },
  { title: 'Address', dataIndex: 'address', key: 'address' },
];

const data: RowData[] = Array.from({ length: 18 }, (_unused, index) => ({
  key: String(index + 1),
  name: `User ${index + 1}`,
  age: 20 + (index % 20),
  address: `No. ${index + 1} Lake Park, ${index % 2 === 0 ? 'London' : 'Sydney'}`,
}));

const scrollArea = ref<HTMLElement | null>(null);

function scrollToBottom(): void {
  const area = scrollArea.value;
  if (!area) return;
  area.scrollTo({ top: area.scrollHeight, behavior: 'smooth' });
}

function scrollToTop(): void {
  scrollArea.value?.scrollTo({ top: 0, behavior: 'smooth' });
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Button type="primary" @click="scrollToBottom">滚动到底部</Button>
      <Button @click="scrollToTop">回到顶部</Button>
      <Tag color="blue">sticky 表头吸附在滚动容器顶部</Tag>
    </Space>

    <div ref="scrollArea" class="sticky-container-demo-scroll">
      <Table
        :columns="columns"
        :data-source="data"
        :pagination="false"
        :sticky="{ offsetHeader: 0 }"
      />
    </div>
  </div>
</template>

<style scoped>
.sticky-container-demo-scroll {
  height: 260px;
  overflow: auto;
  border: 1px solid var(--apollo-color-border);
  border-radius: var(--apollo-border-radius-lg);
}
</style>
```

## 分页位置 (pagination-placement)

使用 `pagination.placement` 同时在上方与下方渲染分页器，可切换位置并实时同步当前页码。

### pagination-placement.vue

```vue
<script setup lang="ts">
import type {
  TableColumnsType,
  TablePaginationConfig,
  TablePaginationPlacement,
  TableProps,
} from '@apollo-design/ui';
import { Select, Space, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

type PlacementMode = 'both' | 'top' | 'bottom';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Age', dataIndex: 'age', key: 'age', width: 100 },
  { title: 'Address', dataIndex: 'address', key: 'address' },
];

const data = Array.from({ length: 23 }, (_unused, index) => ({
  key: String(index + 1),
  name: `User ${index + 1}`,
  age: 20 + (index % 20),
  address: `No. ${index + 1} Lake Park`,
}));

const placementMode = ref<PlacementMode>('both');
const current = ref(1);
const pageSize = ref(5);

const placementOptions: { value: PlacementMode; label: string }[] = [
  { value: 'both', label: '上下都有' },
  { value: 'top', label: '仅顶部' },
  { value: 'bottom', label: '仅底部' },
];

const placement = computed<TablePaginationPlacement[]>(() => {
  if (placementMode.value === 'top') return ['topEnd'];
  if (placementMode.value === 'bottom') return ['bottomCenter'];
  return ['topStart', 'bottomEnd'];
});

const pagination = computed<TablePaginationConfig>(() => ({
  current: current.value,
  pageSize: pageSize.value,
  total: data.length,
  showSizeChanger: true,
  pageSizeOptions: [5, 10],
  placement: placement.value,
}));

const onTableChange: TableProps['onChange'] = (nextPagination) => {
  current.value = nextPagination.current ?? 1;
  pageSize.value = nextPagination.pageSize ?? 5;
};

function onPlacementModeChange(value: unknown): void {
  placementMode.value = value as PlacementMode;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>pagination.placement</span>
      <Select
        aria-label="分页位置"
        :value="placementMode"
        :options="placementOptions"
        style="width: 140px"
        @change="onPlacementModeChange"
      />
      <Tag color="blue">{{ placement.join(', ') }}</Tag>
      <Tag>当前第 {{ current }} 页</Tag>
    </Space>

    <Table
      :columns="columns"
      :data-source="data"
      :pagination="pagination"
      @change="onTableChange"
    >
      <template #paginationTotal="{ total, range }">共 {{ total }} 条</template>
    </Table>
  </div>
</template>
```

## 组件 Token (component-token)

Table 的 Component Token 以 `--apollo-table-*` CSS 变量输出；在容器上覆盖表头、行悬停、单元格内边距等变量即可定制，切换下拉框可对比默认与自定义主题。

### component-token.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 component-token demo。
// 本仓零运行时：Table 的 Component Token 就是 `--apollo-table-*` CSS 变量，
// 在容器上覆盖同名变量即可（37 个 token 见 table/style/index.ts）。
import type { TableColumnsType } from '@apollo-design/ui';
import { Select, Space, Table, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

type TokenMode = 'default' | 'custom';

const mode = ref<TokenMode>('custom');
const modeOptions: { value: TokenMode; label: string }[] = [
  { value: 'default', label: '默认 Token' },
  { value: 'custom', label: '自定义 Token' },
];

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Age', dataIndex: 'age', key: 'age', width: 100, align: 'center' },
  { title: 'City', dataIndex: 'city', key: 'city' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, city: 'New York' },
  { key: '2', name: 'Jim Green', age: 42, city: 'London' },
  { key: '3', name: 'Joe Black', age: 28, city: 'Sydney' },
  { key: '4', name: 'Jim Red', age: 32, city: 'London' },
];

function onModeChange(value: unknown): void {
  mode.value = value as TokenMode;
}
</script>

<template>
  <div class="table-component-token-demo" :class="{ 'is-custom': mode === 'custom' }">
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>Token 主题</span>
      <Select
        aria-label="组件 Token 主题"
        :value="mode"
        :options="modeOptions"
        style="width: 150px"
        @change="onModeChange"
      />
      <Tag color="blue">{{ mode === 'custom' ? '已覆盖表头 / 行 / 内边距' : '默认主题' }}</Tag>
    </Space>

    <Table
      :columns="columns"
      :data-source="data"
      :pagination="false"
      bordered
    ><template #title>用户列表（Component Token）</template></Table>
  </div>
</template>

<style>
.table-component-token-demo.is-custom .apollo-table.apollo-table {
  --apollo-table-header-bg: #e6f4ff;
  --apollo-table-header-color: #0958d9;
  --apollo-table-row-hover-bg: var(--apollo-color-primary-bg);
  --apollo-table-row-selected-bg: var(--apollo-color-primary-bg-hover);
  --apollo-table-cell-padding-block: 12px;
  --apollo-table-cell-padding-inline: 20px;
  --apollo-table-border-color: #91caff;
  --apollo-table-footer-bg: #fffbe6;
}
</style>
```

## 动态设置 (dynamic-settings)

通过开关与下拉框实时切换 `bordered`、`loading`、`showHeader`、`rowHoverable` 与 `size`，表格上方的标签会同步显示当前配置。

### dynamic-settings.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Select, Space, Switch, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

type TableSize = 'large' | 'middle' | 'small';

const bordered = ref(true);
const loading = ref(false);
const showHeader = ref(true);
const rowHoverable = ref(true);
const size = ref<TableSize>('large');

const sizeOptions: { value: TableSize; label: string }[] = [
  { value: 'large', label: 'large' },
  { value: 'middle', label: 'middle' },
  { value: 'small', label: 'small' },
];

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Age', dataIndex: 'age', key: 'age', width: 100 },
  { title: 'City', dataIndex: 'city', key: 'city' },
  { title: 'Email', dataIndex: 'email', key: 'email' },
];

const data = Array.from({ length: 6 }, (_unused, index) => ({
  key: String(index + 1),
  name: `User ${index + 1}`,
  age: 24 + index,
  city: ['London', 'New York', 'Sydney'][index % 3],
  email: `user${index + 1}@example.com`,
}));

const summary = computed(() =>
  [
    bordered.value ? 'bordered' : 'borderless',
    `size=${size.value}`,
    showHeader.value ? 'showHeader' : '隐藏表头',
    rowHoverable.value ? 'hoverable' : '无行悬停',
    loading.value ? 'loading' : 'idle',
  ].join(' · '),
);

function onSizeChange(value: unknown): void {
  size.value = value as TableSize;
}
</script>

<template>
  <div>
    <Space :size="16" wrap style="margin-bottom: 16px">
      <Space :size="6">
        <Switch v-model:checked="bordered" aria-label="显示边框" />
        <span>边框</span>
      </Space>
      <Space :size="6">
        <Switch v-model:checked="loading" aria-label="显示加载状态" />
        <span>加载中</span>
      </Space>
      <Space :size="6">
        <Switch v-model:checked="showHeader" aria-label="显示表头" />
        <span>表头</span>
      </Space>
      <Space :size="6">
        <Switch v-model:checked="rowHoverable" aria-label="启用行悬停" />
        <span>行悬停</span>
      </Space>
      <Select
        aria-label="表格尺寸"
        :value="size"
        :options="sizeOptions"
        style="width: 120px"
        @change="onSizeChange"
      />
    </Space>

    <Tag color="blue" style="margin-bottom: 16px">{{ summary }}</Tag>

    <Table
      :columns="columns"
      :data-source="data"
      :pagination="false"
      :bordered="bordered"
      :loading="loading"
      :show-header="showHeader"
      :row-hoverable="rowHoverable"
      :size="size"
    />
  </div>
</template>
```

## 可编辑行 (edit-row)

点击「编辑本行」后整行切换为表单控件，可修改姓名、年龄与部门；保存后写回本地数据，取消则丢弃草稿并显示当前编辑状态。

### edit-row.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Button, Input, InputNumber, Select, Space, Table, Tag } from '@apollo-design/ui';
import { h, ref } from 'vue';

type Department = 'engineering' | 'design' | 'marketing';

interface EditableRow {
  [key: string]: unknown;
  key: string;
  name: string;
  age: number;
  department: Department;
}

interface DraftRow {
  name: string;
  age: number;
  department: Department;
}

const departmentOptions: { value: Department; label: string }[] = [
  { value: 'engineering', label: 'Engineering' },
  { value: 'design', label: 'Design' },
  { value: 'marketing', label: 'Marketing' },
];

const createRows = (): EditableRow[] => [
  { key: '1', name: 'John Brown', age: 32, department: 'engineering' },
  { key: '2', name: 'Jim Green', age: 42, department: 'design' },
  { key: '3', name: 'Joe Black', age: 28, department: 'marketing' },
];

const data = ref<EditableRow[]>(createRows());
const editingKey = ref<string | null>(null);
const draft = ref<DraftRow>({ name: '', age: 30, department: 'engineering' });
const lastAction = ref('尚未编辑');

function startEdit(record: EditableRow): void {
  editingKey.value = record.key;
  draft.value = {
    name: record.name,
    age: record.age,
    department: record.department,
  };
  lastAction.value = `正在编辑第 ${record.key} 行`;
}

function cancelEdit(): void {
  editingKey.value = null;
  lastAction.value = '已取消编辑';
}

function saveEdit(): void {
  const key = editingKey.value;
  if (!key) return;
  const record = data.value.find((item) => item.key === key);
  if (!record) return;
  const name = draft.value.name.trim();
  record.name = name || record.name;
  record.age = draft.value.age;
  record.department = draft.value.department;
  editingKey.value = null;
  lastAction.value = `第 ${key} 行已保存：${record.name} / ${record.age} / ${record.department}`;
}

function resetRows(): void {
  data.value = createRows();
  editingKey.value = null;
  lastAction.value = '已重置数据';
}

const columns: TableColumnsType = [
  {
    title: 'Name',
    dataIndex: 'name',
    key: 'name',
    width: 190,
    render: (_value: unknown, record: Record<string, unknown>) => {
      const row = record as unknown as EditableRow;
      if (editingKey.value !== row.key) return row.name;
      return h(Input, {
        size: 'small',
        value: draft.value.name,
        'aria-label': `第 ${row.key} 行姓名`,
        'onUpdate:value': (value: string) => {
          draft.value.name = value;
        },
      });
    },
  },
  {
    title: 'Age',
    dataIndex: 'age',
    key: 'age',
    width: 110,
    render: (_value: unknown, record: Record<string, unknown>) => {
      const row = record as unknown as EditableRow;
      if (editingKey.value !== row.key) return row.age;
      return h(InputNumber, {
        size: 'small',
        min: 1,
        max: 120,
        value: draft.value.age,
        'aria-label': `第 ${row.key} 行年龄`,
        style: { width: '86px' },
        'onUpdate:value': (value: string | number | null) => {
          if (value !== null) draft.value.age = Number(value);
        },
      });
    },
  },
  {
    title: 'Department',
    dataIndex: 'department',
    key: 'department',
    width: 180,
    render: (_value: unknown, record: Record<string, unknown>) => {
      const row = record as unknown as EditableRow;
      if (editingKey.value !== row.key) return row.department;
      return h(Select, {
        size: 'small',
        value: draft.value.department,
        options: departmentOptions,
        'aria-label': `第 ${row.key} 行部门`,
        style: { width: '150px' },
        'onUpdate:value': (value: unknown) => {
          draft.value.department = value as Department;
        },
      });
    },
  },
  {
    title: 'Action',
    key: 'action',
    width: 170,
    render: (_value: unknown, record: Record<string, unknown>) => {
      const row = record as unknown as EditableRow;
      if (editingKey.value !== row.key) {
        return h(
          Button,
          { type: 'link', size: 'small', onClick: () => startEdit(row) },
          { default: () => '编辑本行' },
        );
      }
      return h(
        Space,
        { size: 8 },
        {
          default: () => [
            h(
              Button,
              { type: 'primary', size: 'small', onClick: saveEdit },
              { default: () => '保存' },
            ),
            h(Button, { size: 'small', onClick: cancelEdit }, { default: () => '取消' }),
          ],
        },
      );
    },
  },
];
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Button @click="resetRows">重置数据</Button>
      <Tag :color="editingKey ? 'blue' : 'default'">
        {{ editingKey ? `编辑中：第 ${editingKey} 行` : '当前没有行处于编辑态' }}
      </Tag>
      <span>{{ lastAction }}</span>
    </Space>

    <Table :columns="columns" :data-source="data" :pagination="false" />
  </div>
</template>
```

## 省略与自定义 Tooltip (ellipsis-custom-tooltip)

列设置 `ellipsis: { showTitle: false }` 关闭原生 title，再在 `render` 中用 Tooltip 展示完整内容；切换下拉框可实时改变浮层方位。

### ellipsis-custom-tooltip.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Select, Space, Table, Tag, Tooltip } from '@apollo-design/ui';
import { computed, h, ref } from 'vue';

type TooltipPlacement = 'topLeft' | 'top' | 'topRight';

const placement = ref<TooltipPlacement>('topLeft');
const placementOptions: { value: TooltipPlacement; label: string }[] = [
  { value: 'topLeft', label: 'topLeft' },
  { value: 'top', label: 'top' },
  { value: 'topRight', label: 'topRight' },
];

interface RowData {
  [key: string]: unknown;
  key: string;
  name: string;
  description: string;
}

const data: RowData[] = [
  {
    key: '1',
    name: 'Long text',
    description:
      'This is a very long description that will be truncated in the table cell, and the full content is shown in a custom tooltip instead of the native title attribute.',
  },
  {
    key: '2',
    name: 'Another row',
    description:
      'Hover the ellipsis text to inspect the custom placement. The tooltip content comes from render(), so it can be composed freely.',
  },
  {
    key: '3',
    name: 'Short',
    description: 'Short content still uses the same custom tooltip.',
  },
];

const columns = computed<TableColumnsType>(() => [
  { title: 'Name', dataIndex: 'name', key: 'name', width: 130 },
  {
    title: 'Description（自定义 Tooltip）',
    dataIndex: 'description',
    key: 'description',
    width: 320,
    ellipsis: { showTitle: false },
    render: (_value: unknown, record: Record<string, unknown>) =>
      h(
        Tooltip,
        { title: String(record.description), placement: placement.value },
        {
          default: () => h('span', { style: { cursor: 'help' } }, String(record.description)),
        },
      ),
  },
]);

function onPlacementChange(value: unknown): void {
  placement.value = value as TooltipPlacement;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>Tooltip 方位</span>
      <Select
        aria-label="Tooltip 方位"
        :value="placement"
        :options="placementOptions"
        style="width: 130px"
        @change="onPlacementChange"
      />
      <Tag color="blue">{{ placement }}</Tag>
    </Space>

    <Table
      :columns="columns"
      :data-source="data"
      :pagination="false"
      style="max-width: 560px"
    />
  </div>
</template>
```

## 展开行与吸附表头 (expand-sticky)

在可滚动容器中同时启用 `sticky` 表头与 `#expandedRow` 插槽，滚动时表头保持吸附，展开行仍可独立控制。

### expand-sticky.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableExpandableConfig, TableKey } from '@apollo-design/ui';
import { Button, Space, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

interface RowData {
  key: string;
  name: string;
  owner: string;
  progress: number;
}

const columns: TableColumnsType<RowData> = [
  { title: 'Task', dataIndex: 'name', key: 'name' },
  { title: 'Owner', dataIndex: 'owner', key: 'owner', width: 140 },
  { title: 'Progress', dataIndex: 'progress', key: 'progress', width: 120 },
];

const data: RowData[] = Array.from({ length: 14 }, (_unused, index) => ({
  key: String(index + 1),
  name: `Release checklist ${index + 1}`,
  owner: ['Alice', 'Bob', 'Carol', 'David'][index % 4] ?? 'Alice',
  progress: 20 + index * 5,
}));

const allKeys = data.map((item) => item.key);
const expandedRowKeys = ref<TableKey[]>(['1', '2']);

const expandable = computed<TableExpandableConfig<RowData>>(() => ({
  expandedRowKeys: expandedRowKeys.value,
  onExpandedRowsChange: (keys: TableKey[]) => {
    expandedRowKeys.value = keys;
  },
}));

function expandAll(): void {
  expandedRowKeys.value = [...allKeys];
}

function collapseAll(): void {
  expandedRowKeys.value = [];
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Button type="primary" @click="expandAll">全部展开</Button>
      <Button @click="collapseAll">全部收起</Button>
      <Tag color="blue">已展开 {{ expandedRowKeys.length }} 行</Tag>
    </Space>

    <div class="expand-sticky-demo-scroll">
      <Table
        :columns="columns"
        :data-source="data"
        :pagination="false"
        :expandable="expandable"
        :sticky="{ offsetHeader: 0 }"
      >
        <template #expandedRow="{record}"><div style="display:flex;gap:24px;align-items:center;flex-wrap:wrap"><strong>任务详情 #{{record.key}}</strong><span>负责人：{{record.owner}}</span><span>当前进度：{{record.progress}}%</span><span>滚动容器内的 sticky 表头会保持吸附。</span></div></template>
      </Table>
    </div>
  </div>
</template>

<style scoped>
.expand-sticky-demo-scroll {
  height: 300px;
  overflow: auto;
  border: 1px solid var(--apollo-color-border);
  border-radius: var(--apollo-border-radius-lg);
}
</style>
```

## 表头与扩展区 (head)

`title` 接收渲染函数，可放置标题、数量和刷新按钮；`footer` 提供表格底部内容，排序与筛选变化会同步显示在页面上方。

### head.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableProps } from '@apollo-design/ui';
import { Button, Space, Table, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const refreshCount = ref(0);
const lastAction = ref('等待操作');
const showFilters = ref(false);

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  {
    title: 'Age',
    dataIndex: 'age',
    key: 'age',
    width: 100,
    sorter: (a: Record<string, unknown>, b: Record<string, unknown>) =>
      (a.age as number) - (b.age as number),
  },
  {
    title: 'Role',
    dataIndex: 'role',
    key: 'role',
    filters: [
      { text: 'Engineer', value: 'engineer' },
      { text: 'Designer', value: 'designer' },
      { text: 'Manager', value: 'manager' },
    ],
    onFilter: (value: unknown, record: Record<string, unknown>) => record.role === value,
  },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, role: 'engineer' },
  { key: '2', name: 'Jim Green', age: 42, role: 'designer' },
  { key: '3', name: 'Joe Black', age: 28, role: 'manager' },
  { key: '4', name: 'Jim Red', age: 32, role: 'engineer' },
  { key: '5', name: 'Alice White', age: 36, role: 'designer' },
];

function refresh(): void {
  refreshCount.value += 1;
  showFilters.value = true;
  lastAction.value = `第 ${refreshCount.value} 次刷新：头部按钮与表格联动`;
}

const onTableChange: TableProps['onChange'] = (_pagination, _filters, sorter) => {
  const field = (sorter as { field?: string }).field;
  lastAction.value = field ? `排序字段：${field}` : '排序已清除';
};
</script>

<template>
  <div>
    <div style="margin-bottom: 16px">
      <Tag color="blue">{{ lastAction }}</Tag>
    </div>

    <Table
      :columns="columns"
      :data-source="data"
      :pagination="false"
      @change="onTableChange"
    >
      <template #title="{data:rows}">
        <div style="display:flex;align-items:center;justify-content:space-between;gap:16px;flex-wrap:wrap">
          <div style="display:flex;align-items:center;gap:8px"><strong>用户列表</strong><Tag color="blue">{{rows.length}} 行</Tag></div>
          <Space :size="12"><Button size="small" @click="refresh">刷新（{{refreshCount}}）</Button><Tag :color="showFilters?'green':'default'">{{showFilters?'已刷新':'待刷新'}}</Tag></Space>
        </div>
      </template>
      <template #footer>表头与底部均由 Table 的原生插槽渲染</template>
    </Table>
  </div>
</template>
```

## 隐藏列 (hidden-columns)

列的 `hidden` 属性会在保留列定义的同时移除表头与单元格，开关可实时切换 Age、City 和 Email 列并显示可见列数量。

### hidden-columns.vue

```vue
<script setup lang="ts">
import type { TableColumnsType } from '@apollo-design/ui';
import { Space, Switch, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const showAge = ref(true);
const showCity = ref(true);
const showEmail = ref(false);

const columns = computed<TableColumnsType>(() => [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Age', dataIndex: 'age', key: 'age', width: 100, hidden: !showAge.value },
  { title: 'City', dataIndex: 'city', key: 'city', hidden: !showCity.value },
  { title: 'Email', dataIndex: 'email', key: 'email', hidden: !showEmail.value },
]);

const data = [
  { key: '1', name: 'John Brown', age: 32, city: 'New York', email: 'john@example.com' },
  { key: '2', name: 'Jim Green', age: 42, city: 'London', email: 'jim@example.com' },
  { key: '3', name: 'Joe Black', age: 28, city: 'Sydney', email: 'joe@example.com' },
  { key: '4', name: 'Jim Red', age: 32, city: 'London', email: 'red@example.com' },
];

const visibleCount = computed(
  () => [true, showAge.value, showCity.value, showEmail.value].filter(Boolean).length,
);
</script>

<template>
  <div>
    <Space :size="16" wrap style="margin-bottom: 16px">
      <Space :size="6">
        <Switch v-model:checked="showAge" aria-label="显示年龄列" />
        <span>Age</span>
      </Space>
      <Space :size="6">
        <Switch v-model:checked="showCity" aria-label="显示城市列" />
        <span>City</span>
      </Space>
      <Space :size="6">
        <Switch v-model:checked="showEmail" aria-label="显示邮箱列" />
        <span>Email</span>
      </Space>
      <Tag color="blue">{{ visibleCount }} / 4 列可见</Tag>
    </Space>

    <Table :columns="columns" :data-source="data" :pagination="false" />
  </div>
</template>
```

## 嵌套子表格 (nested-table)

`#expandedRow` 插槽 返回另一个 Table，展示每位客户的最近订单；按钮可展开或收起全部父行，子表格使用独立列与本地数据。

### nested-table.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableExpandableConfig, TableKey } from '@apollo-design/ui';
import { Button, Space, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

interface OuterRow {
  key: string;
  name: string;
  department: string;
  email: string;
}

const columns: TableColumnsType<OuterRow> = [
  { title: 'Customer', dataIndex: 'name', key: 'name' },
  { title: 'Department', dataIndex: 'department', key: 'department', width: 160 },
  { title: 'Email', dataIndex: 'email', key: 'email' },
];

const data: OuterRow[] = [
  {
    key: '1',
    name: 'Alice',
    department: 'Engineering',
    email: 'alice@example.com',
  },
  {
    key: '2',
    name: 'Bob',
    department: 'Design',
    email: 'bob@example.com',
  },
  {
    key: '3',
    name: 'Carol',
    department: 'Marketing',
    email: 'carol@example.com',
  },
];

const innerColumns: TableColumnsType = [
  { title: 'Order', dataIndex: 'order', key: 'order', width: 140 },
  { title: 'Amount', dataIndex: 'amount', key: 'amount', width: 120, align: 'right' },
  { title: 'Status', dataIndex: 'status', key: 'status' },
];

const innerData: Record<string, Record<string, unknown>[]> = {
  '1': [
    { key: '1-1', order: 'SO-1001', amount: 1280, status: 'Paid' },
    { key: '1-2', order: 'SO-1002', amount: 560, status: 'Pending' },
  ],
  '2': [
    { key: '2-1', order: 'SO-1003', amount: 890, status: 'Paid' },
    { key: '2-2', order: 'SO-1004', amount: 2400, status: 'Shipped' },
  ],
  '3': [{ key: '3-1', order: 'SO-1005', amount: 430, status: 'Refunded' }],
};

const allKeys = data.map((item) => item.key);
const expandedRowKeys = ref<TableKey[]>(['1', '2']);

const expandable = computed<TableExpandableConfig<OuterRow>>(() => ({
  expandedRowKeys: expandedRowKeys.value,
  onExpandedRowsChange: (keys: TableKey[]) => {
    expandedRowKeys.value = keys;
  },
}));

function expandAll(): void {
  expandedRowKeys.value = [...allKeys];
}

function collapseAll(): void {
  expandedRowKeys.value = [];
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Button type="primary" @click="expandAll">展开全部客户</Button>
      <Button @click="collapseAll">收起全部</Button>
      <Tag color="blue">已展开 {{ expandedRowKeys.length }} 行</Tag>
    </Space>

    <Table
      :columns="columns"
      :data-source="data"
      :pagination="false"
      :expandable="expandable"
      bordered
    >
      <template #expandedRow="{record}"><div style="padding:12px 0 4px"><div style="font-weight:600;margin-bottom:8px">最近订单 · {{record.name}}</div><Table :columns="innerColumns" :data-source="innerData[record.key]??[]" :pagination="false" size="small" /></div></template>
    </Table>
  </div>
</template>
```

## 分页 (pagination)

受控 `pagination` 配置每页条数、快速跳页与总数展示；翻页或在每页条数下拉框中切换后，页面标签会同步当前页码与页大小。

### pagination.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TablePaginationConfig, TableProps } from '@apollo-design/ui';
import { Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Age', dataIndex: 'age', key: 'age', width: 100 },
  { title: 'City', dataIndex: 'city', key: 'city' },
];

const data = Array.from({ length: 42 }, (_unused, index) => ({
  key: String(index + 1),
  name: `User ${index + 1}`,
  age: 20 + (index % 20),
  city: ['London', 'New York', 'Sydney'][index % 3],
}));

const current = ref(1);
const pageSize = ref(5);

const pagination = computed<TablePaginationConfig>(() => ({
  current: current.value,
  pageSize: pageSize.value,
  total: data.length,
  showSizeChanger: true,
  pageSizeOptions: [5, 10, 20],
  showQuickJumper: true,
}));

const onTableChange: TableProps['onChange'] = (nextPagination) => {
  current.value = nextPagination.current ?? 1;
  pageSize.value = nextPagination.pageSize ?? 5;
};
</script>

<template>
  <div>
    <Tag color="blue" style="margin-bottom: 16px">
      当前第 {{ current }} 页，每页 {{ pageSize }} 条（共 {{ data.length }} 条）
    </Tag>

    <Table
      :columns="columns"
      :data-source="data"
      :pagination="pagination"
      @change="onTableChange"
    >
      <template #paginationTotal="{ total, range }">第 {{ range[0] }}-{{ range[1] }} 条 / 共 {{ total }} 条</template>
    </Table>
  </div>
</template>
```

## 重置筛选 (reset-filter)

筛选状态通过列上的 `filteredValue` 受控；点击「重置筛选」把两列的受控值置为 `null`，表格数据与筛选图标同步恢复，页面标签记录当前条件。

### reset-filter.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableFilterValue, TableProps } from '@apollo-design/ui';
import { Button, Space, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const nameFilter = ref<TableFilterValue | null>(null);
const roleFilter = ref<TableFilterValue | null>(null);
const lastAction = ref('尚未筛选');

const columns = computed<TableColumnsType>(() => [
  {
    title: 'Name',
    dataIndex: 'name',
    key: 'name',
    filters: [
      { text: 'John Brown', value: 'John Brown' },
      { text: 'Jim Green', value: 'Jim Green' },
      { text: 'Joe Black', value: 'Joe Black' },
    ],
    filteredValue: nameFilter.value,
    onFilter: (value: unknown, record: Record<string, unknown>) =>
      String(record.name).includes(String(value)),
  },
  {
    title: 'Role',
    dataIndex: 'role',
    key: 'role',
    filterMultiple: false,
    filters: [
      { text: 'Engineer', value: 'engineer' },
      { text: 'Designer', value: 'designer' },
      { text: 'Manager', value: 'manager' },
    ],
    filteredValue: roleFilter.value,
    onFilter: (value: unknown, record: Record<string, unknown>) => record.role === value,
  },
  { title: 'City', dataIndex: 'city', key: 'city' },
]);

const data = [
  { key: '1', name: 'John Brown', role: 'engineer', city: 'New York' },
  { key: '2', name: 'Jim Green', role: 'designer', city: 'London' },
  { key: '3', name: 'Joe Black', role: 'manager', city: 'Sydney' },
  { key: '4', name: 'Jim Red', role: 'engineer', city: 'London' },
];

const activeFilters = computed(() => {
  const labels: string[] = [];
  if (nameFilter.value?.length) labels.push(`姓名：${nameFilter.value.map(String).join('、')}`);
  if (roleFilter.value?.length) labels.push(`角色：${roleFilter.value.map(String).join('、')}`);
  return labels;
});

const onTableChange: TableProps['onChange'] = (_pagination, filters) => {
  nameFilter.value = filters.name ?? null;
  roleFilter.value = filters.role ?? null;
  lastAction.value = '筛选条件已更新';
};

function resetFilters(): void {
  nameFilter.value = null;
  roleFilter.value = null;
  lastAction.value = '已重置全部筛选条件';
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Button @click="resetFilters">重置筛选</Button>
      <Tag color="blue">{{ lastAction }}</Tag>
      <Tag>{{ activeFilters.length ? activeFilters.join('；') : '当前无筛选条件' }}</Tag>
    </Space>

    <Table
      :columns="columns"
      :data-source="data"
      :pagination="false"
      @change="onTableChange"
    />
  </div>
</template>
```

## 自定义选择项 (row-selection-custom)

通过 `rowSelection.selections` 提供「全选所有行」「清空选择」「仅选择偶数年龄」三个自定义菜单项，并保留禁用行；页面会显示当前选择与最近一次选择方式。

### row-selection-custom.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableKey, TableRowSelection } from '@apollo-design/ui';
import { Button, Space, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

interface RowData {
  [key: string]: unknown;
  key: string;
  name: string;
  age: number;
  role: string;
}

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Age', dataIndex: 'age', key: 'age', width: 100 },
  { title: 'Role', dataIndex: 'role', key: 'role' },
];

const data: RowData[] = [
  { key: '1', name: 'John Brown', age: 32, role: 'Engineer' },
  { key: '2', name: 'Jim Green', age: 42, role: 'Designer' },
  { key: '3', name: 'Joe Black', age: 28, role: 'Manager' },
  { key: '4', name: 'Disabled User', age: 40, role: 'Guest' },
  { key: '5', name: 'Jim Red', age: 33, role: 'Engineer' },
];

const selectedRowKeys = ref<TableKey[]>([]);
const lastAction = ref('尚未选择');

const selectedNames = computed(() =>
  data.filter((row) => selectedRowKeys.value.includes(row.key)).map((row) => row.name),
);

const rowSelection = computed<TableRowSelection>(() => ({
  selectedRowKeys: selectedRowKeys.value,
  onChange: (keys: TableKey[], _rows: Record<string, unknown>[], info) => {
    selectedRowKeys.value = keys;
    lastAction.value = `选择方式：${info.type}`;
  },
  getCheckboxProps: (record: Record<string, unknown>) => ({
    disabled: record.name === 'Disabled User',
  }),
  selections: [
    {
      key: 'all',
      text: '全选所有行',
      onSelect: () => {
        selectedRowKeys.value = data
          .filter((row) => row.name !== 'Disabled User')
          .map((row) => row.key);
        lastAction.value = '自定义项：全选所有行';
      },
    },
    {
      key: 'clear',
      text: '清空选择',
      onSelect: () => {
        selectedRowKeys.value = [];
        lastAction.value = '自定义项：清空选择';
      },
    },
    {
      key: 'even',
      text: '仅选择偶数年龄',
      onSelect: () => {
        selectedRowKeys.value = data
          .filter((row) => row.age % 2 === 0 && row.name !== 'Disabled User')
          .map((row) => row.key);
        lastAction.value = '自定义项：仅选择偶数年龄';
      },
    },
  ],
}));

function clearSelection(): void {
  selectedRowKeys.value = [];
  lastAction.value = '已从页面按钮清空选择';
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Button :disabled="!selectedRowKeys.length" @click="clearSelection">清空选择</Button>
      <Tag color="blue">{{ lastAction }}</Tag>
      <Tag>
        {{ selectedNames.length ? `已选：${selectedNames.join('、')}` : '当前未选择任何行' }}
      </Tag>
    </Space>

    <Table
      :columns="columns"
      :data-source="data"
      :row-selection="rowSelection"
      :pagination="false"
    />
  </div>
</template>
```

## 语义化样式 (style-class)

用 `classNames` 给根、标题、表头、表体与底部挂语义类名，用 `styles` 注入内联样式；切换 Blue / Warm 会同步改变边框、表头与行背景。

### style-class.vue

```vue
<script setup lang="ts">
import type {
  TableColumnsType,
  TableSemanticClassNames,
  TableSemanticStyles,
} from '@apollo-design/ui';
import { Select, Space, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

type StyleTheme = 'blue' | 'warm';

const theme = ref<StyleTheme>('blue');
const themeOptions: { value: StyleTheme; label: string }[] = [
  { value: 'blue', label: 'Blue' },
  { value: 'warm', label: 'Warm' },
];

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Age', dataIndex: 'age', key: 'age', width: 100 },
  { title: 'City', dataIndex: 'city', key: 'city' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, city: 'New York' },
  { key: '2', name: 'Jim Green', age: 42, city: 'London' },
  { key: '3', name: 'Joe Black', age: 28, city: 'Sydney' },
  { key: '4', name: 'Jim Red', age: 32, city: 'London' },
];

const classNames = computed<TableSemanticClassNames>(() => ({
  root: 'table-style-class-root',
  title: 'table-style-class-title',
  header: {
    wrapper: 'table-style-class-header',
    row: 'table-style-class-header-row',
    cell: 'table-style-class-header-cell',
  },
  body: {
    row: 'table-style-class-body-row',
    cell: 'table-style-class-body-cell',
  },
  footer: 'table-style-class-footer',
}));

const styles = computed<TableSemanticStyles>(() => ({
  root: {
    border: `1px solid ${theme.value === 'blue' ? '#91caff' : '#ffd591'}`,
    borderRadius: '12px',
    overflow: 'hidden',
  },
  title: {
    padding: '14px 18px',
    fontWeight: '600',
  },
  header: {
    cell: {
      background: theme.value === 'blue' ? '#e6f4ff' : '#fff7e6',
      color: theme.value === 'blue' ? '#0958d9' : '#ad4e00',
      letterSpacing: '0.02em',
    },
  },
  body: {
    row: {
      background: theme.value === 'blue' ? '#fbfdff' : '#fffdf7',
      color: '#1f1f1f',
    },
  },
  footer: {
    padding: '12px 18px',
  },
}));

function onThemeChange(value: unknown): void {
  theme.value = value as StyleTheme;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>语义样式主题</span>
      <Select
        aria-label="语义样式主题"
        :value="theme"
        :options="themeOptions"
        style="width: 120px"
        @change="onThemeChange"
      />
      <Tag color="blue">{{ theme }}</Tag>
    </Space>

    <Table
      :columns="columns"
      :data-source="data"
      :pagination="false"
      :class-names="classNames"
      :styles="styles"
    ><template #title>Style Class</template><template #footer>classNames / styles 同时作用于根、表头、表体与标题槽</template></Table>
  </div>
</template>

<style>
.table-style-class-root .table-style-class-header-cell {
  font-weight: 600;
}

.table-style-class-root .table-style-class-body-row:hover > td {
  transition: background-color 0.2s ease;
}

.table-style-class-footer {
  color: var(--apollo-color-text-secondary);
}
</style>
```

## 树形表格省略 (tree-table-ellipsis)

树形数据配合固定列宽与 `ellipsis`：层级缩进和展开图标保留，超长名称与描述被截断并保留原生 title；按钮可展开或收起根节点。

### tree-table-ellipsis.vue

```vue
<script setup lang="ts">
import type { TableColumnsType, TableExpandableConfig, TableKey } from '@apollo-design/ui';
import { Button, Space, Table, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

interface TreeRow {
  [key: string]: unknown;
  key: string;
  name: string;
  description: string;
  owner: string;
  children?: TreeRow[];
}

const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'name', key: 'name', width: 210, ellipsis: true },
  {
    title: 'Description',
    dataIndex: 'description',
    key: 'description',
    width: 300,
    ellipsis: true,
  },
  { title: 'Owner', dataIndex: 'owner', key: 'owner', width: 110 },
];

const data: TreeRow[] = [
  {
    key: '1',
    name: 'Design system foundation',
    description:
      'Design tokens, theme algorithms and shared CSS variables used by every component package.',
    owner: 'Alice',
    children: [
      {
        key: '1-1',
        name: 'Color tokens and semantic aliases',
        description:
          'Seed, map and alias token layers with a generated CSS variable contract for runtime and static styling.',
        owner: 'Bob',
        children: [
          {
            key: '1-1-1',
            name: 'Dark theme algorithm validation',
            description:
              'Validate dark theme output against the visual baseline and keep the token names stable.',
            owner: 'Carol',
          },
        ],
      },
      {
        key: '1-2',
        name: 'Typography scale',
        description: 'Font size, line height and heading spacing shared across data-dense pages.',
        owner: 'David',
      },
    ],
  },
  {
    key: '2',
    name: 'Interaction patterns',
    description:
      'Keyboard navigation, focus rings and hover feedback for complex data entry workflows.',
    owner: 'Eve',
    children: [
      {
        key: '2-1',
        name: 'Table keyboard navigation',
        description: 'Arrow keys, Home / End and expandable row behavior inside scrollable tables.',
        owner: 'Frank',
      },
    ],
  },
];

const allKeys = data.map((item) => item.key);
const expandedRowKeys = ref<TableKey[]>(['1']);

const expandable = computed<TableExpandableConfig>(() => ({
  expandedRowKeys: expandedRowKeys.value,
  onExpandedRowsChange: (keys: TableKey[]) => {
    expandedRowKeys.value = keys;
  },
}));

function expandAll(): void {
  expandedRowKeys.value = [...allKeys];
}

function collapseAll(): void {
  expandedRowKeys.value = [];
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Button type="primary" @click="expandAll">展开全部</Button>
      <Button @click="collapseAll">收起全部</Button>
      <Tag color="blue">已展开 {{ expandedRowKeys.length }} 个根节点</Tag>
      <Tag>悬停省略文本可查看完整内容</Tag>
    </Space>

    <Table
      :columns="columns"
      :data-source="data"
      :pagination="false"
      :expandable="expandable"
      :scroll="{ x: 640 }"
      style="max-width: 680px"
    />
  </div>
</template>
```

---

# Tabs

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/tabs


# Tabs 标签页

选项卡切换组件，提供平级区域的内容切换能力。

## 何时使用

- 提供平级的区域将大块内容进行收纳和展现，保持界面整洁；
- 需要让用户在一个区域内的多个视图间快速切换时。

## 引入

```ts
import { Tabs } from '@apollo-design/ui';
```

## 代码演示































## API

### Tabs

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| activeKey | 受控激活项，支持 `v-model:activeKey` | `string` | — |
| defaultActiveKey | 非受控初始激活项 | `string` | 首个启用项 |
| items | 页签与面板数据 | `TabsItem[]` | `[]` |
| type | 页签类型 | `'line' \| 'card' \| 'editable-card'` | `'line'` |
| size | 局部尺寸；依次回落到 `components.tabs.size`、全局尺寸 | `'small' \| 'medium' \| 'middle' \| 'large'` | — |
| tabPlacement | 导航位置；start/end 按文字方向映射 | `'top' \| 'end' \| 'bottom' \| 'start'` | `'top'` |
| direction | 文字方向，未传读取当前 Provider | `'ltr' \| 'rtl'` | — |
| centered | 导航居中 | `boolean` | `false` |
| tabBarGutter | 相邻页签的间距，单位 px | `number` | — |
| tabBarStyle | 导航区样式 | `CSSProperties` | — |
| tabBarExtraContent | 附加内容；单节点位于右侧 | `VNodeChild \| { left?: VNodeChild; right?: VNodeChild }` | — |
| addIcon / removeIcon | 新增与关闭按钮图标 | `VNodeChild` | — |
| hideAdd | 隐藏新增按钮，仅用于 editable-card | `boolean` | `false` |
| more | 溢出按钮图标与浮层动效名 | `{ icon?: VNodeChild; transitionName?: string }` | — |
| indicator | 指示条对齐与长度；函数接收原始长度 | `{ align?: 'start' \| 'center' \| 'end'; size?: number \| ((origin: number) => number) }` | `{ align: 'center' }` |
| animated | 指示条与面板动画 | `boolean \| { inkBar?: boolean; tabPane?: boolean }` | `{ inkBar: true, tabPane: false }` |
| destroyOnHidden | 未设置 item 配置时，隐藏面板是否销毁 | `boolean` | `false` |
| locale | 按钮与溢出列表的可访问名称 | `{ dropdownAriaLabel?: string; removeAriaLabel?: string; addAriaLabel?: string }` | 英文默认名称 |
| getPopupContainer | 溢出浮层的挂载容器 | `(trigger: HTMLElement) => HTMLElement` | 当前 Provider / body |
| classNames / styles | 语义区域对象，或 `({ props: TabsProps }) => 对象` | `TabsProps['classNames'] / TabsProps['styles']` | — |
| id | 根 id 与内部 ARIA id 的前缀 | `string` | Vue `useId()` |
| prefixCls | DOM 类名前缀 | `string` | `'apollo-tabs'` |

保留的废弃别名：`tabPosition`（top/right/bottom/left）、`indicatorSize`、`moreIcon`、`popupClassName`、`destroyInactiveTabPane`。优先使用 tabPlacement、indicator.size、more.icon、classNames.popup.root、destroyOnHidden。

### TabsItem

| 字段 | 说明 | 类型 |
| --- | --- | --- |
| key | 唯一数据键；事件始终传回原值 | `string` |
| label / children | 页签标题 / 面板内容，支持完整 Vue 内容和数字 0 | `VNodeChild` |
| icon | 标题图标 | `VNodeChild` |
| disabled | 禁止用户激活与移除 | `boolean` |
| closable | 是否可移除，仅用于 editable-card | `boolean` |
| closeIcon | 当 closable 未设置时，null/false 会关闭该项的移除能力 | `VNodeChild` |
| forceRender | 激活前也渲染该面板 | `boolean` |
| destroyOnHidden | 覆盖组件级隐藏销毁默认值，包括显式 false | `boolean` |
| destroyInactiveTabPane | destroyOnHidden 的废弃别名 | `boolean` |
| className / style | 面板区域的类名 / 样式 | `string / CSSProperties` |

### 事件

| 事件 | 触发与参数 |
| --- | --- |
| update:activeKey | 激活请求不同于当前公开值时，`(key: string)` |
| change | 与 update:activeKey 同次发送，`(key: string)` |
| tabClick | 每次有效页签点击或键盘激活，包括当前项，`(key: string, event: MouseEvent \| KeyboardEvent)` |
| tabScroll | 导航位移变化，`({ direction: 'left' \| 'right' \| 'top' \| 'bottom' })` |
| edit | 新增发送 `(event, 'add')`，移除发送 `(key, 'remove')`；数据由调用方更新 |

事件统一由 Vue emits 发送，不另调用监听器 prop。受控请求须由父级接受才改变公开值；activeKey 变为 undefined 时保留最后一次实际接受的值。默认值只初始化一次。非受控激活项被移除时，按原索引选择附近的启用项；数据整理本身不发送用户激活事件。

### 插槽与实例

| 插槽 | 作用域 |
| --- | --- |
| tabBar | `TabsRenderTabBarProps`：当前 id、prefixCls、tabs、activeKey、方向、位置、动画、样式及导航回调；整体替换导航 |
| popupRender | `{ originNode, restTabs, onClose }`：原始溢出列表、当前隐藏项与关闭方法 |
| extra | `{ position: 'left' \| 'right' }`：两侧附加内容 |

插槽在渲染时读取。extra 插槽存在时优先于 tabBarExtraContent，空槽也会压住默认内容；popupRender 同样支持条件出现、空内容和撤除。tabBar 自定义导航负责自己的键盘与 ARIA；editable.onEdit 的 remove 命令必须提供 `{ key, event }`，add 命令提供 `{ event }`。

模板 ref 的 `nativeElement` 是实际根 `HTMLElement | null` 属性：`tabsRef.value?.nativeElement`。不调用 nativeElement()。

### 原生属性、语义与焦点

class、style、data-*、ARIA 和未声明的原生事件落在根 div。根 style 支持对象、数组与字符串，优先于组件语义根样式。语义区域为 root、header、item、remove、indicator、body、content，以及嵌套的 popup.root；Provider 样式先合并，再由局部语义样式和原生根 style 覆盖。函数式语义样式收到当前解析后的 props。

页签与关闭按钮各自拥有交互，tablist 通过 aria-owns 只拥有 tab；溢出 listbox 只拥有 option，移除按钮是独立控件。数据 key 的 id 片段会编码，避免空白或标点破坏 ARIA 关联。未显式传 id 时，SSR 与水合使用 Vue 的确定 id。相同 key 的面板在重排时保留输入和组件状态。

| 按键 | 行为 |
| --- | --- |
| 左 / 右 | 横向导航，在启用项间循环，RTL 反转方向；阻止已处理的默认滚动 |
| 上 / 下 | 纵向导航；横向时保留页面默认行为 |
| Home / End | 首个 / 最后一个启用项 |
| Enter / Space | 激活焦点项 |
| Backspace / Delete | 对可移除的焦点项发送 edit；只有数据实际移除后才移动焦点 |
| 溢出按钮的上 / 下 / Enter / Space | 打开并聚焦溢出列表；上键从最后一项开始 |
| 溢出列表的上 / 下、Home / End | 跳过禁用项移动当前选项 |
| 溢出列表的 Enter / Space、Escape | 选择并关闭 / 关闭，焦点返回溢出按钮 |

溢出按钮支持鼠标悬停与点击，点击外部关闭。关闭图标与自定义插槽中的表单控件保留自己的键盘操作。禁用的当前项不会取消其他启用项的 Tab 入口。触摸移动、惯性、观察器与浮层监听在取消、换目标和卸载时清理。

## 设计 Token

24 个组件 Token 读取当前 `ConfigProvider.theme.components.Tabs`，支持嵌套、替换、撤除和全局派生。数值长度使用 px，zIndexPopup 为无单位数值；浮层使用同一套当前 Token。

| Token | 默认值 / 派生 |
| --- | --- |
| zIndexPopup | 1050 |
| cardBg / cardGutter | colorFillAlter / 2 |
| cardHeight / cardHeightSM / cardHeightLG | 40 / 32 / 48；控制新增按钮最小尺寸与默认 padding 派生 |
| cardPadding / cardPaddingSM / cardPaddingLG | 8px 16px / 4px 8px / 11px 16px；高度覆盖后重新派生，显式 padding 优先 |
| titleFontSize / titleFontSizeLG / titleFontSizeSM | 14 / 16 / 14 |
| inkBarColor | colorPrimary |
| horizontalMargin | 0 0 16px 0 |
| horizontalItemGutter | 32，可覆盖 |
| horizontalItemPadding / horizontalItemPaddingSM / horizontalItemPaddingLG | 12px 0 / 8px 0 / 16px 0 |
| verticalItemPadding / verticalItemMargin | 8px 24px / 16px 0 0 0 |
| itemColor | colorText |
| itemSelectedColor / itemHoverColor / itemActiveColor | 亮背景取 colorPrimaryTextActive，暗背景取 colorPrimaryTextHover |

默认文字三状态复用当前主题中已有的可读主色；背景明暗分类与 Button 相同，不生成新色值。显式 item*Color、原生样式、透明或自定义背景由调用方保证实际色对可读。样式仍由静态 CSS 与 CSS 变量消费；自定义 prefixCls 需要配套静态选择器。

### 开发版直接迁移

移除无实现的顶层 children，使用 items[].children。移除从未消费的 horizontalItemMargin / horizontalItemMarginRTL，使用 horizontalItemGutter。已声明为属性的 nativeElement 修正为真实元素，旧函数调用改为属性读取；id 在 SSR 首帧即生效，key 片段编码。item.destroyOnHidden 现在按既有文档覆盖组件默认值。以上没有兼容层或弃用期。

既有 popupRender 单对象与条件插槽迁移保留，见 [2026-10-24 迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/tabs-popup-slots.md)。原始 DOM/视觉参考保留；本阶段验证不等同于冻结版本的整库最终验收。


## 基本 (basic)

默认选中第一项。用 `v-model:activeKey` 受控。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd `basic.tsx`。
import { Tabs } from '@apollo-design/ui';
import { ref } from 'vue';

const activeKey = ref('1');
const items = [
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
  { key: '3', label: 'Tab 3', children: 'Content of Tab Pane 3' },
];
</script>

<template>
  <Tabs v-model:active-key="activeKey" :items="items" />
</template>
```

## 禁用 (disabled)

`items[].disabled` 的页签不可点、**焦点也跳不过去**。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd `disabled.tsx`。
import { Tabs } from '@apollo-design/ui';
import { ref } from 'vue';

const activeKey = ref('1');
const items = [
  { key: '1', label: 'Tab 1', children: 'Tab 1' },
  { key: '2', label: 'Tab 2', children: 'Tab 2', disabled: true },
  { key: '3', label: 'Tab 3', children: 'Tab 3' },
];
</script>

<template>
  <Tabs v-model:active-key="activeKey" :items="items" />
</template>
```

## 带图标 (icon)

`items[].icon` + 字符串 label 时，label 会被包一层 `<span>`（上游同款）。

### icon.vue

```vue
<script setup lang="ts">
// 对齐 antd `icon.tsx`。⚠️ 图标用 `h(Icon)` 生成 VNode（`items[].icon` 的类型是 `VNodeChild`）；
//    `icon` 与**字符串** label 同时存在时，label 会被包一层 `<span>`（上游同款）。
import { AndroidOutlined, AppleOutlined } from '@apollo-design/icons';
import { Tabs } from '@apollo-design/ui';
import { h } from 'vue';

const items = [
  { key: '1', label: 'Tab 1', icon: h(AppleOutlined), children: 'Tab 1' },
  { key: '2', label: 'Tab 2', icon: h(AndroidOutlined), children: 'Tab 2' },
];
</script>

<template>
  <Tabs default-active-key="1" :items="items" />
</template>
```

## 尺寸 (size)

`size` 三档：`small` / 默认 / `large`（各自有独立的 padding token）。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd `size.tsx`。
import { Tabs } from '@apollo-design/ui';
import { ref } from 'vue';

const items = [
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
];
const small = ref('1');
const large = ref('1');
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Tabs v-model:active-key="small" size="small" :items="items" />
    <Tabs v-model:active-key="large" size="large" :items="items" />
  </div>
</template>
```

## 位置 (placement)

`tabPlacement` 四值；`start`/`end` 会按 RTL 映射成 `left`/`right`。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd `placement.tsx`。
import { Tabs } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Tabs default-active-key="1" tab-placement="top" :items="items" />
    <Tabs default-active-key="1" tab-placement="bottom" :items="items" />
    <Tabs default-active-key="1" tab-placement="start" :items="items" />
    <Tabs default-active-key="1" tab-placement="end" :items="items" />
  </div>
</template>
```

## 卡片式 (card)

`type="card"` 的卡片页签；`tabBarGutter` 可调页签间距。

### card.vue

```vue
<script setup lang="ts">
// 对齐 antd `card.tsx`。
import { Tabs } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Tabs default-active-key="1" type="card" :items="items" />
    <Tabs default-active-key="1" type="card" :tab-bar-gutter="36" :items="items" />
  </div>
</template>
```

## 居中 (centered)

`centered` 让卡片式页签整体居中。

### centered.vue

```vue
<script setup lang="ts">
// 对齐 antd `centered.tsx`。
import { Tabs } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
];
</script>

<template>
  <Tabs default-active-key="1" type="card" centered :items="items" />
</template>
```

## 可增删 (editable-card)

`type="editable-card"`：`@edit` 的载荷是**改写过的**（add 传事件、remove 传 key）。

### editable-card.vue

```vue
<script setup lang="ts">
// 对齐 antd `editable-card.tsx`。⚠️ 载荷改写规则与 antd 一致：
// `@edit="(target, action) => …"` —— action 是 `'add' | 'remove'`；
// add 时 target 是**事件对象**，remove 时 target 是 **key**。
import { Tabs } from '@apollo-design/ui';
import { ref } from 'vue';

const items = ref([
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
]);
const activeKey = ref('1');
let nextKey = 3;

// ⚠️ 第二个形参的类型必须是 **`string`**（与 `Tabs` 的 emits 声明 `(_target, _action: string)`
//    一致）—— 写成 `'add' | 'remove'` 会因「参数逆变」被判为不可赋值（`string` 不能赋给
//    那个更窄的联合）。收窄发生在**函数体内**，不在签名上。
const onEdit = (target: unknown, action: string): void => {
  if (action === 'remove') {
    const index = items.value.findIndex((item) => item.key === target);
    items.value = items.value.filter((item) => item.key !== target);
    if (activeKey.value === target)
      activeKey.value = items.value[Math.max(0, index - 1)]?.key ?? '';
    return;
  }
  const next = String(nextKey++);
  items.value = [...items.value, { key: next, label: `Tab ${next}`, children: `Content ${next}` }];
  activeKey.value = next;
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Tabs v-model:active-key="activeKey" type="editable-card" :items="items" @edit="onEdit" />
    <Tabs type="editable-card" hide-add :items="items" @edit="onEdit" />
  </div>
</template>
```

## 自定义新增触发器 (custom-add-trigger)

`addIcon` 换掉「+」的图标。新增后切换到新页签，关闭当前页签时选择相邻项；递增键避免删除后新增产生重复键。

### custom-add-trigger.vue

```vue
<script setup lang="ts">
// 对齐 antd `custom-add-trigger.tsx`。
import { PlusCircleOutlined } from '@apollo-design/icons';
import { Tabs, type TabsEditAction, type TabsEditEvent } from '@apollo-design/ui';
import { h, ref } from 'vue';

const items = ref([
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
]);
const activeKey = ref('1');
let nextKey = 3;

function onEdit(target: TabsEditEvent | string, action: TabsEditAction): void {
  if (action === 'add') {
    const key = String(nextKey++);
    items.value.push({ key, label: `Tab ${key}`, children: `Content of Tab Pane ${key}` });
    activeKey.value = key;
    return;
  }
  const index = items.value.findIndex((item) => item.key === target);
  items.value = items.value.filter((item) => item.key !== target);
  if (activeKey.value === target) activeKey.value = items.value[Math.max(0, index - 1)]?.key ?? '';
}
</script>

<template>
  <Tabs
    v-model:active-key="activeKey"
    type="editable-card"
    :items="items"
    :add-icon="h(PlusCircleOutlined)"
    @edit="onEdit"
  />
</template>
```

## 附加内容 (extra)

`tabBarExtraContent` 两形态：单节点（右侧）或 `{ left, right }`。

### extra.vue

```vue
<script setup lang="ts">
// 对齐 antd `extra.tsx`。
import { Button, Tabs } from '@apollo-design/ui';
import { h } from 'vue';

const items = [
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Tabs
      default-active-key="1"
      :items="items"
      :tab-bar-extra-content="h(Button, null, () => 'Right extra action')"
    />
    <Tabs
      default-active-key="1"
      :items="items"
      :tab-bar-extra-content="{ left: h('span', { style: { marginInlineEnd: '12px' } }, 'Left extra action'), right: h(Button, null, () => 'Right extra action') }"
    />
  </div>
</template>
```

## 自定义指示条 (custom-indicator)

`indicator` 的 `align`（start/center/end）与 `size`（定长）。

### custom-indicator.vue

```vue
<script setup lang="ts">
// 对齐 antd `custom-indicator.tsx`（只演示 align 与 size 两个通道；
// 上游 demo 里的 `styles.indicator` 走的是语义槽，本仓同样支持 `styles`）。
import { Tabs } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Tabs default-active-key="1" :items="items" :indicator="{ align: 'start' }" />
    <Tabs default-active-key="1" :items="items" :indicator="{ size: 20 }" />
    <Tabs default-active-key="1" :items="items" :indicator="{ align: 'end', size: (origin: number) => origin * 0.5 }" />
  </div>
</template>
```

## 自定义导航区 (custom-tab-bar)

`#tabBar` 槽整体替换导航区（替代 `renderTabBar`）。这里使用 Apollo `Button`，补齐 tablist / tab 语义、面板关联及方向键、Home、End 导航。

### custom-tab-bar.vue

```vue
<script setup lang="ts">
// 对齐 antd `custom-tab-bar.tsx`。⚠️ Vue 侧是 **scoped slot**（C8），
// 槽参数 = 上游 `renderTabBar` 的第一个实参（含 activeKey / items / onTabClick / extra …）。
import { Button, Tabs } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
];

function onKeydown(event: KeyboardEvent): void {
  if (!['ArrowRight', 'ArrowLeft', 'Home', 'End'].includes(event.key)) return;
  if (!(event.currentTarget instanceof HTMLElement)) return;
  event.preventDefault();
  const tabs = Array.from(
    event.currentTarget.parentElement?.querySelectorAll<HTMLButtonElement>('[role="tab"]') ?? [],
  );
  const index = tabs.findIndex((tab) => tab === event.currentTarget);
  const next =
    event.key === 'Home'
      ? 0
      : event.key === 'End'
        ? tabs.length - 1
        : (index + (event.key === 'ArrowRight' ? 1 : -1) + tabs.length) % tabs.length;
  tabs[next]?.focus();
  tabs[next]?.click();
}
</script>

<template>
  <Tabs default-active-key="1" :items="items">
    <template #tabBar="{ id, activeKey, onTabClick }">
      <div role="tablist" aria-label="Custom tab bar" style="display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 16px">
        <Button
          v-for="item in items"
          :key="item.key"
          :id="`${id}-tab-${item.key}`"
          :type="item.key === activeKey ? 'primary' : 'default'"
          role="tab"
          :aria-selected="item.key === activeKey"
          :aria-controls="`${id}-panel-${item.key}`"
          :tabindex="item.key === activeKey ? 0 : -1"
          :style="{ fontWeight: item.key === activeKey ? 700 : 400 }"
          @click="(e: MouseEvent) => onTabClick(item.key, e)"
          @keydown="onKeydown"
        >
          {{ item.label }}
        </Button>
      </div>
    </template>
  </Tabs>
</template>
```

## 动画 (animated)

`animated` 三形态；默认是 `{ inkBar: true, tabPane: false }`（**面板默认无动画**）。

### animated.vue

```vue
<script setup lang="ts">
// 对齐 antd `animated.tsx`。
import { Tabs } from '@apollo-design/ui';

const items = [
  { key: '1', label: 'Tab 1', children: 'Content of Tab Pane 1' },
  { key: '2', label: 'Tab 2', children: 'Content of Tab Pane 2' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Tabs default-active-key="1" :items="items" />
    <Tabs default-active-key="1" :items="items" :animated="true" />
    <Tabs default-active-key="1" :items="items" :animated="{ inkBar: true, tabPane: false }" />
  </div>
</template>
```

## 卡片式页签 (card-top)

使用 `type="card"` 渲染卡片式页签，并通过 `tabPlacement` 在顶部与底部之间切换导航栏位置。

### card-top.vue

```vue
<script setup lang="ts">
import type { TabPlacement } from '@apollo-design/ui';
import { Select, Space, Tabs, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const activeKey = ref('1');
const placement = ref<TabPlacement>('top');

const placementOptions: { value: TabPlacement; label: string }[] = [
  { value: 'top', label: 'top（顶部）' },
  { value: 'bottom', label: 'bottom（底部）' },
];

const items = [
  { key: '1', label: '概览', children: '卡片式页签位于内容顶部，适合展示模块分组。' },
  { key: '2', label: '配置', children: '切换 tabPlacement 可以将同一组页签移动到内容底部。' },
  { key: '3', label: '日志', children: '当前激活页签由 v-model:activeKey 受控。' },
];

function onPlacementChange(value: unknown): void {
  placement.value = value as TabPlacement;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>tabPlacement</span>
      <Select
        :value="placement"
        :options="placementOptions"
        style="width: 160px"
        @change="onPlacementChange"
      />
      <Tag color="blue">activeKey: {{ activeKey }}</Tag>
    </Space>

    <Tabs
      v-model:active-key="activeKey"
      type="card"
      :tab-placement="placement"
      :items="items"
    />
  </div>
</template>
```

## 组件 Token (component-token)

通过 ConfigProvider 的 `theme.components.Tabs` 覆盖指示条、选中文字、字号与间距。切换预设会更新当前页签与溢出浮层的组件 Token；原生 `style` 仍可覆盖根节点的 CSS 变量。

### component-token.vue

```vue
<script setup lang="ts">
import { ConfigProvider, Select, Space, Tabs, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const presets = [
  {
    value: 'blue',
    label: '默认蓝',
    inkBar: '#1677ff',
    selected: '#002c8c',
    hover: '#003eb3',
    fontSize: 14,
    gutter: 32,
  },
  {
    value: 'purple',
    label: '紫罗兰',
    inkBar: '#722ed1',
    selected: '#722ed1',
    hover: '#531dab',
    fontSize: 16,
    gutter: 24,
  },
  {
    value: 'green',
    label: '青绿色',
    inkBar: '#389e0d',
    selected: '#237804',
    hover: '#135200',
    fontSize: 18,
    gutter: 16,
  },
];

type PresetValue = (typeof presets)[number]['value'];

const preset = ref<PresetValue>('blue');
const activeKey = ref('1');

const currentPreset = computed(
  () =>
    presets.find((item) => item.value === preset.value) ?? {
      inkBar: '#1677ff',
      selected: '#002c8c',
      hover: '#003eb3',
      fontSize: 14,
      gutter: 32,
    },
);

const theme = computed(() => ({
  components: {
    Tabs: {
      inkBarColor: currentPreset.value.inkBar,
      itemSelectedColor: currentPreset.value.selected,
      itemHoverColor: currentPreset.value.hover,
      titleFontSize: currentPreset.value.fontSize,
      horizontalItemGutter: currentPreset.value.gutter,
    },
  },
}));

const items = [
  { key: '1', label: '设计规范', children: '指示条颜色、选中文字颜色与字号由组件 Token 控制。' },
  {
    key: '2',
    label: '开发指南',
    children: '切换配色预设会实时更新 ConfigProvider 的 Tabs 组件 Token。',
  },
  { key: '3', label: '发布记录', children: '页签间距来自 --apollo-tabs-horizontal-item-gutter。' },
];

function onPresetChange(value: unknown): void {
  if (value === 'blue' || value === 'purple' || value === 'green') preset.value = value;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>主题配色</span>
      <Select
        :value="preset"
        :options="presets"
        style="width: 140px"
        @change="onPresetChange"
      />
      <Tag color="blue">字号 {{ currentPreset.fontSize }}</Tag>
      <Tag>页签间距 {{ currentPreset.gutter }}</Tag>
    </Space>

    <ConfigProvider :theme="theme">
      <Tabs v-model:active-key="activeKey" :items="items" />
    </ConfigProvider>
  </div>
</template>
```

## 自定义页签节点 (custom-tab-bar-node)

`#tabBar` 插槽可以直接渲染自定义页签节点。本例刻意保留原生按钮，展示自行构建导航时的语义与焦点职责；常规按钮用法见「自定义页签栏」。示例补齐了 `tablist` / `tab` 角色、`aria-selected`、`aria-controls` 与 id 关联，并实现左右方向键、Home、End 的焦点移动与切换。

### custom-tab-bar-node.vue

```vue
<script setup lang="ts">
// 自定义页签节点：刻意保留原生 button，演示自建 tablist 的 ARIA 与焦点职责。
import { Tabs } from '@apollo-design/ui';

const items = [
  { key: '1', label: '概览', forceRender: true, children: '概览面板：展示核心指标与最近动态。' },
  { key: '2', label: '成员', forceRender: true, children: '成员面板：管理团队成员与权限。' },
  {
    key: '3',
    label: '设置',
    forceRender: true,
    children: '设置面板：调整通知、主题与集成。',
  },
];

function onTabKeydown(
  event: KeyboardEvent,
  index: number,
  onTabClick: (key: string, event: KeyboardEvent) => void,
): void {
  if (!['ArrowRight', 'ArrowLeft', 'Home', 'End'].includes(event.key)) {
    return;
  }
  event.preventDefault();
  const current = event.currentTarget as HTMLElement | null;
  const buttons = current?.parentElement?.querySelectorAll<HTMLButtonElement>('[role="tab"]');
  const list = buttons ? Array.from(buttons) : [];
  if (!list.length) {
    return;
  }
  let nextIndex = index;
  if (event.key === 'Home') {
    nextIndex = 0;
  } else if (event.key === 'End') {
    nextIndex = list.length - 1;
  } else {
    const offset = event.key === 'ArrowRight' ? 1 : -1;
    nextIndex = (index + offset + list.length) % list.length;
  }
  list[nextIndex]?.focus();
  const nextItem = items[nextIndex];
  if (nextItem) {
    onTabClick(nextItem.key, event);
  }
}
</script>

<template>
  <Tabs id="demo-custom-tab-bar-node" default-active-key="1" :items="items">
    <template #tabBar="{ id, activeKey, onTabClick }">
      <div role="tablist" aria-label="自定义页签导航" class="demo-tab-bar-node">
        <button
          v-for="(item, index) in items"
          :id="id ? `${id}-tab-${item.key}` : undefined"
          :key="item.key"
          type="button"
          role="tab"
          :aria-selected="item.key === activeKey"
          :aria-controls="id ? `${id}-panel-${item.key}` : undefined"
          :tabindex="item.key === activeKey ? 0 : -1"
          class="demo-tab-bar-node__tab"
          :class="{ 'demo-tab-bar-node__tab--active': item.key === activeKey }"
          @click="(event: MouseEvent) => onTabClick(item.key, event)"
          @keydown="(event: KeyboardEvent) => onTabKeydown(event, index, onTabClick)"
        >
          <span class="demo-tab-bar-node__dot" aria-hidden="true" />
          {{ item.label }}
        </button>
      </div>
    </template>
  </Tabs>
</template>

<style>
.demo-tab-bar-node {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
  padding: 6px;
  border-radius: 999px;
  background: var(--apollo-color-fill-secondary);
}

.demo-tab-bar-node__tab {
  display: inline-flex;
  align-items: center;
  gap: 8px;
  padding: 6px 16px;
  border: 1px solid transparent;
  border-radius: 999px;
  background: transparent;
  color: var(--apollo-color-text-secondary);
  font: inherit;
  cursor: pointer;
}

.demo-tab-bar-node__tab:hover {
  color: var(--apollo-color-primary);
}

.demo-tab-bar-node__tab--active {
  border-color: var(--apollo-color-primary-border);
  background: var(--apollo-color-bg-container);
  color: var(--apollo-color-primary-text);
  box-shadow: 0 2px 6px rgb(114 46 209 / 16%);
}

.demo-tab-bar-node__tab:focus-visible {
  outline: 2px solid var(--apollo-color-primary);
  outline-offset: 2px;
}

.demo-tab-bar-node__dot {
  width: 8px;
  height: 8px;
  border-radius: 50%;
  background: currentColor;
}
</style>
```

## 嵌套页签 (nest)

在页签内容中再渲染一组 `Tabs`。内层使用 `size="small"` 与独立的 `defaultActiveKey`，外层内容通过 `items[].children` 传入 VNode。

### nest.vue

```vue
<script setup lang="ts">
// 嵌套页签：在页签内容中再放一组 Tabs
import { Tabs } from '@apollo-design/ui';
import { h } from 'vue';

const innerItems = [
  { key: '1', label: '接口文档', children: '接口文档：请求参数、响应示例与错误码。' },
  { key: '2', label: '变更日志', children: '变更日志：按版本记录 API 调整。' },
  { key: '3', label: '示例代码', children: '示例代码：Vue 3 + TypeScript 调用示例。' },
];

const innerTabs = h('div', { style: 'padding-top: 8px' }, [
  h(Tabs, { defaultActiveKey: '1', size: 'small', items: innerItems }),
]);

const outerItems = [
  { key: '1', label: '开发资源', children: innerTabs },
  { key: '2', label: '设计资源', children: '设计资源：组件规范、色彩与图标下载。' },
  {
    key: '3',
    label: '团队协作',
    children: '团队协作：需求评审、联调与发布流程。',
  },
];
</script>

<template>
  <Tabs default-active-key="1" :items="outerItems" />
</template>
```

## 滑动切换 (slide)

`animated` 的对象形态可以同时开启指示条与面板动画。示例使用 `{ inkBar: true, tabPane: true }`，切换页签时观察面板进入与离开的过渡。

### slide.vue

```vue
<script setup lang="ts">
// 滑动切换：开启面板动画（animated.tabPane）
import { Tabs } from '@apollo-design/ui';

const items = [
  { key: '1', label: '第一步', children: '填写基本信息，切换页签查看面板过渡。' },
  { key: '2', label: '第二步', children: '上传相关材料，面板会以切换动效进入。' },
  { key: '3', label: '第三步', children: '确认并提交，指示条与面板同时参与动画。' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: 440px; max-width: 100%">
    <Tabs
      default-active-key="1"
      :items="items"
      :animated="{ inkBar: true, tabPane: true }"
    />
    <p style="margin: 0; color: var(--apollo-color-text-secondary); font-size: 12px">
      animated.tabPane 为 true 时启用面板切换动效；默认值为 { inkBar: true, tabPane: false }。
    </p>
  </div>
</template>
```

## 自定义溢出菜单 (popup-render)

使用 `#popupRender="{ originNode, restTabs, onClose }"` 接收原始菜单、隐藏页签和关闭动作。可在挂载后添加或移除插槽；空插槽隐藏内容，不回退默认菜单。原始菜单保留页签选择行为。

<!-- en-US -->

Use the named slot object to access the original menu, hidden tabs and close action. Add or remove the slot after mount; an empty slot suppresses the default menu. The original menu retains tab selection.

### popup-render.vue

```vue
<script setup lang="ts">
import { Button, Tabs } from '@apollo-design/ui';
import { ref } from 'vue';

const custom = ref(false);
const empty = ref(false);
const label = ref('Hidden tabs');
const activeKey = ref('1');
const items = Array.from({ length: 12 }, (_, index) => ({
  key: String(index + 1),
  label: `Tab ${index + 1}`,
  children: `Panel ${index + 1}`,
}));
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 12px">
    <Button @click="custom = !custom">Toggle popup slot</Button>
    <Button @click="empty = !empty">Toggle empty popup</Button>
    <Button @click="label = label === 'Hidden tabs' ? 'More tabs' : 'Hidden tabs'">Update popup label</Button>
  </div>
  <Tabs v-model:activeKey="activeKey" :items="items" style="width: 280px; max-width: 100%">
    <template v-if="custom" #popupRender="{ originNode, restTabs, onClose }">
      <section v-if="!empty" data-tabs-popup style="padding: 8px; background: var(--apollo-color-bg-elevated); color: var(--apollo-color-text)">
        <p data-tabs-popup-summary>{{ label }}: {{ restTabs.length }}</p>
        <component :is="originNode" />
        <Button @click="onClose">Close tabs popup</Button>
      </section>
    </template>
  </Tabs>
  <output data-tabs-active>{{ activeKey }}</output>
</template>
```

## 语义化样式与类 (style-class)

Tabs 的语义槽覆盖根节点、导航栏、页签项、指示条与内容区。`classNames` 拼接类名，`styles` 覆盖对应槽位；示例用紫色指示条与浅色内容区展示组合效果。

### style-class.vue

```vue
<script setup lang="ts">
// 语义化样式与类：root / header / item / indicator / content
import type { TabsProps } from '@apollo-design/ui';
import { Tabs } from '@apollo-design/ui';

const classNames: TabsProps['classNames'] = {
  root: 'demo-tabs-style',
  header: 'demo-tabs-style__header',
  item: 'demo-tabs-style__item',
  indicator: 'demo-tabs-style__indicator',
  content: 'demo-tabs-style__content',
};

const styles: TabsProps['styles'] = {
  header: {
    backgroundColor: '#f9f0ff',
    color: '#391085',
    paddingInline: '12px',
    borderRadius: '8px 8px 0 0',
  },
  item: { letterSpacing: '0.4px', color: '#391085' },
  indicator: { backgroundColor: '#722ed1' },
  content: {
    backgroundColor: '#fcfaff',
    color: '#391085',
    padding: '16px',
    borderRadius: '0 0 8px 8px',
  },
};

const items = [
  { key: '1', label: '设计', children: '设计面板：组件规范与视觉基线。' },
  { key: '2', label: '开发', children: '开发面板：API 文档与示例代码。' },
  { key: '3', label: '测试', children: '测试面板：单元、DOM 契约与可访问性报告。' },
];
</script>

<template>
  <Tabs
    default-active-key="1"
    :items="items"
    :class-names="classNames"
    :styles="styles"
  />
</template>

<style>
.demo-tabs-style__item {
  font-weight: 500;
}

.demo-tabs-style__indicator {
  height: 3px;
}
</style>
```

---

# Tag

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/tag


标记属性和分类。交互选择使用 CheckableTag 或 CheckableTagGroup。

## 代码演示

十二个 [Demo](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/tag/demo) 覆盖基本链接/关闭、勾选、颜色、动态添加、自定义、禁用、拖拽、图标、状态、四语义样式、关闭重置和组件 Token。

## API

### Tag

| Prop | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | DOM 类名前缀；自定义前缀需对应静态 CSS | `string` | `apollo-tag` |
| color | 13 预设色、success/processing/error/warning/default 或合法 CSS 色值 | `TagColor` | — |
| variant | 变体 | `'filled' \| 'solid' \| 'outlined'` | `filled` |
| bordered | 已有废弃字段，false 相当于 filled；使用 variant | `boolean` | — |
| closable | 关闭开关/配置，包含 closeIcon、disabled、aria-*、data-* | `boolean \| TagClosableConfig \| null` | `false` |
| href / target | 内部链接地址/打开方式 | `string` | — |
| disabled | 禁用链接及关闭操作；省略时采用全局禁用配置 | `boolean` | `false` |
| classNames / styles | root、icon、content、close 四语义区域 | `TagSemanticClassNames / TagSemanticStyles` | — |

| Slot | 内容 |
|---|---|
| default | 完整正文 |
| icon | 完整前置图标内容 |
| closeIcon | 完整关闭内容；存在时优先于配置，显式空槽抑制按钮 |

| Emit | 参数与行为 |
|---|---|
| close | 原生 `MouseEvent`；`preventDefault()` 取消隐藏。停止关闭点击向根外传播 |

根固定为 span，icon/content/close 有独立语义宿主。href 使用 content 内的 a；关闭按钮为其兄弟元素，保留调用者图标的属性与监听器。关闭按钮消费 Enter/空格的 keydown 冒泡，保留原生默认激活，避免父级选择控件误处理。默认关闭保留 DOM 并添加 `-hidden`；父级可通过卸载重挂恢复。

### CheckableTag

| Prop | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prefixCls | 标签前缀 | `string` | `apollo-tag` |
| checked | 受控选择状态，支持 `v-model:checked`；省略为非受控 | `boolean` | `false` |
| disabled | 禁用选择 | `boolean` | `false` |

插槽：default、icon，均保留完整内容。事件：`update:checked(boolean)`、`change(boolean)`、`click(MouseEvent)`、`keydown(KeyboardEvent)`。点击/空格更新一次；Enter 不切换；重复空格不重复更新，原生事件 `preventDefault()` 可取消切换。checkbox 的 role/aria-checked/禁用 tabindex 由组件维护。

### CheckableTagGroup

| Prop | 说明 | 类型 | 默认值 |
|---|---|---|---|
| id / prefixCls | 根 id / 标签前缀（Group 类名追加 -checkable-group） | `string` | — / `apollo-tag` |
| options | 原始值或选项；label 省略时显示 value | `(T \| CheckableTagOption<T>)[]`，T 为 string/number | `[]` |
| value | 受控模型，支持 `v-model:value` | 单选 `T \| null`；多选 `T[]` | — |
| defaultValue | 非受控初始值，仅挂载时读取 | 同 value | 单选 null，多选 [] |
| multiple | 多选模式 | `boolean` | `false` |
| disabled | 禁用全部选项 | `boolean` | `false` |
| classNames / styles | 仅 root/item；option.className/style 应用到对应选择项，option.style 最后覆盖 item 样式 | `GroupSemanticClassNames / GroupSemanticStyles` | — |

选项包含 value、可选 label（VNodeChild 数据）、className、style。Group 不提供公开插槽。事件：`update:value(value)`、`change(value)`，模型由 multiple 泛型确定，单次交互各发一次。动态 options/multiple/value 更新当前显示；切换模式不自动改写父模型，下次交互按当前模式输出。单选再次点击当前项回到 null。空字符串/数字 0 是有效值。

## Expose、attrs 与 Provider

三组件均公开 `nativeElement`（Tag/CheckableTag 为根 span，Group 为 div），保留 `Tag.CheckableTag` / `Tag.CheckableTagGroup` 与同名具名导出身份。原生根 class/style/id/data、监听器采用 Vue 合并规则；字符串/数组/对象 style 均支持，根原生 style 最后覆盖语义样式。CheckableTag 的事件使用 Vue `@keydown`。

Tag 链接专属 rel/download/hreflang/referrerpolicy/tabindex/accesskey、aria-label/labelledby/describedby 和 focus/blur 监听器落到真实 a；其他 attrs 落到根。Provider 的方向/禁用及 components.tag 当前样式即时生效；Tag 额外消费 variant/closable/closeIcon/classNames/styles。选择组件不消费 Tag 的关闭或 variant 配置。明确本地字段覆盖 Provider，移除后恢复当前配置。

## Theme

| Component Token | 默认来源 | 说明 |
|---|---|---|
| defaultBg | colorFillTertiary 叠加 colorBgContainer | 默认底色 |
| defaultColor | colorText | 默认文字色 |
| solidTextColor | 实际 solid 背景自动选择黑白色 | solid 文字色；显式配置保留调用者控制 |

通过 `ConfigProvider.theme.components.Tag` 配置，动态替换/移除即时生效。预设/状态/自定义色保留三变体，filled/outlined 文字按当前主题调整明度以保证可读性，选择态使用实际背景决定前景。显式文字色与背景应合理配对。兼容边界和旧/新写法见 [迁移记录](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/tag-contracts.md)。


## 基本用法 (basic)

最简单的用法（含链接、阻止默认关闭行为）。

### basic.vue

```vue
<script setup lang="ts">
import { CloseCircleOutlined } from '@apollo-design/icons';
import { Space, Tag } from '@apollo-design/ui';

const preventDefault = (e: MouseEvent) => {
  e.preventDefault();
  console.log('Clicked! But prevent default.');
};
</script>

<template>
  <Space wrap>
    <Tag>Tag 1</Tag>
    <Tag href="https://github.com" target="_blank" rel="noopener noreferrer">Link</Tag>
    <Tag closable @close="preventDefault">
      Prevent Default
      <template #closeIcon><CloseCircleOutlined /></template>
    </Tag>
    <Tag closable>Tag 2</Tag>
  </Space>
</template>
```

## 可勾选 (checkable)

使用 `v-model:checked` 与 `v-model:value`，展示独立勾选、单选及多选；空格键切换当前项。

### checkable.vue

```vue
<script setup lang="ts">
import { CheckableTag, CheckableTagGroup } from '@apollo-design/ui';
import { ref } from 'vue';

const tagsData = ['Movies', 'Books', 'Music', 'Sports'];
const checked = ref(true);
const singleSelected = ref<string | null>('Books');
const multipleSelected = ref<string[]>(['Movies', 'Music']);
</script>

<template>
  <p>Checkable: <CheckableTag v-model:checked="checked">Yes</CheckableTag></p>
  <p>Single: <CheckableTagGroup v-model:value="singleSelected" :options="tagsData" aria-label="Single interest" /></p>
  <p>Multiple: <CheckableTagGroup v-model:value="multipleSelected" :options="tagsData" multiple aria-label="Multiple interests" /></p>
</template>
```

## 多彩标签 (colorful)

三种 variant ×（预设色 / 状态色 / 自定义色）。

每组使用 `Space wrap`，`column-gap` / `row-gap` 均为 8px；Tag 本身仍保留零外边距。
Each group uses `Space wrap` with 8px column and row gaps, without changing Tag margins.

### colorful.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 colorful demo
import { Space, Tag } from '@apollo-design/ui';

const variants = ['filled', 'solid', 'outlined'] as const;
const presets = [
  'magenta',
  'red',
  'volcano',
  'orange',
  'gold',
  'lime',
  'green',
  'cyan',
  'blue',
  'geekblue',
  'purple',
];
const status = ['success', 'processing', 'error', 'warning', 'default'];
const customs = ['#f50', '#2db7f5', '#87d068', '#108ee9'];
</script>

<template>
  <div v-for="variant in variants" :key="variant">
    <p>Presets ({{ variant }})</p>
    <Space wrap :size="[8, 8]">
      <Tag v-for="p in presets" :key="p" :color="p" :variant="variant">{{ p }}</Tag>
    </Space>
    <p>Status ({{ variant }})</p>
    <Space wrap :size="[8, 8]">
      <Tag v-for="s in status" :key="s" :color="s" :variant="variant">{{ s }}</Tag>
    </Space>
    <p>Custom ({{ variant }})</p>
    <Space wrap :size="[8, 8]">
      <Tag v-for="c in customs" :key="c" :color="c" :variant="variant">{{ c }}</Tag>
    </Space>
  </div>
</template>
```

## 动态添加和关闭 (control)

用数组生成标签。点击 New Tag 后输入框获得焦点；Enter 或失焦提交，自动去重，可逐个关闭。

### control.vue

```vue
<script setup lang="ts">
import { PlusOutlined } from '@apollo-design/icons';
import { Button, type ButtonRef, Input, type InputRef, Space, Tag } from '@apollo-design/ui';
import { nextTick, ref } from 'vue';

const tags = ref(['Tag 1', 'Tag 2', 'Tag 3']);
const inputVisible = ref(false);
const inputValue = ref('');
const input = ref<InputRef | null>(null);
const addButton = ref<ButtonRef | null>(null);

const showInput = async () => {
  inputVisible.value = true;
  await nextTick();
  input.value?.focus();
};
const handleInputConfirm = async () => {
  if (!inputVisible.value) return;
  const text = inputValue.value.trim();
  if (text && !tags.value.includes(text)) {
    tags.value = [...tags.value, text];
  }
  inputVisible.value = false;
  inputValue.value = '';
  await nextTick();
  addButton.value?.nativeElement?.focus();
};

const handleClose = (removed: string) => {
  tags.value = tags.value.filter((t) => t !== removed);
};
</script>

<template>
  <Space wrap>
    <Tag v-for="tag in tags" :key="tag" closable @close="handleClose(tag)">{{ tag }}</Tag>
    <Input
      v-if="inputVisible"
      ref="input"
      v-model:value="inputValue"
      type="text"
      aria-label="New tag name"
      :style="{ width: '78px', marginRight: '8px', verticalAlign: 'top' }"
      @blur="handleInputConfirm"
      @keydown.enter.prevent="handleInputConfirm"
    />
    <Button v-else ref="addButton" size="small" @click="showInput">
      <PlusOutlined aria-hidden="true" /> New Tag
    </Button>
  </Space>
</template>
```

## 自定义 (customize)

自定义图标与颜色；原生按钮通过 `aria-pressed` 表示开关状态，支持点击、Enter 和空格。

### customize.vue

```vue
<script setup lang="ts">
import {
  FacebookOutlined,
  LinkedinOutlined,
  TwitterOutlined,
  YoutubeOutlined,
} from '@apollo-design/icons';
import { Space, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const checked = ref([true, false, false, false]);
const icons = [TwitterOutlined, YoutubeOutlined, FacebookOutlined, LinkedinOutlined];
const colors = ['magenta', 'volcano', 'orange', 'gold'];

const toggle = (i: number) => {
  checked.value = checked.value.map((c, idx) => (idx === i ? !c : c));
};
</script>

<template>
  <Space wrap>
  <button v-for="(item, i) in icons" :key="i" type="button" class="demo-tag-toggle" :aria-pressed="checked[i]" @click="toggle(i)">
    <Tag :color="checked[i] ? colors[i] : undefined">
      <template #icon><component :is="item" aria-hidden="true" /></template>
      {{ colors[i] }}
    </Tag>
  </button>
  </Space>
</template>
<style scoped>
.demo-tag-toggle { padding: 0; border: 0; background: transparent; color: inherit; font: inherit; cursor: pointer; }
.demo-tag-toggle:focus-visible { outline: 2px solid var(--apollo-color-primary); outline-offset: 2px; }
</style>
```

## 不可关闭和禁用 (disabled)

禁用状态的标签（关闭按钮与交互均禁用）。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 disabled demo
import { Space, Tag } from '@apollo-design/ui';
</script>

<template>
  <Space wrap>
    <Tag closable disabled>Closable</Tag>
    <Tag disabled>Disabled</Tag>
  </Space>
</template>
```

## 可拖拽 (draggable)

使用原生 HTML 拖拽事件重排标签。此 Demo 演示指针拖拽，不提供键盘排序。

### draggable.vue

```vue
<script setup lang="ts">
import { Space, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const items = ref([
  { id: 1, text: 'Tag 1' },
  { id: 2, text: 'Tag 2' },
  { id: 3, text: 'Tag 3' },
]);

const dragIndex = ref(-1);

const onDragStart = (i: number) => {
  dragIndex.value = i;
};
const onDrop = (i: number) => {
  const from = dragIndex.value;
  dragIndex.value = -1;
  if (from < 0 || from === i) return;
  const next = [...items.value];
  const moved = next.splice(from, 1)[0];
  if (!moved) return;
  next.splice(i, 0, moved);
  items.value = next;
  dragIndex.value = -1;
};
</script>

<template>
  <Space wrap>
  <Tag
    v-for="(item, i) in items"
    :key="item.id"
    draggable="true"
    :style="{ cursor: 'move' }"
    @dragstart="onDragStart(i)"
    @dragend="dragIndex = -1"
    @dragover.prevent
    @drop="onDrop(i)"
  >
    {{ item.text }}
  </Tag>
  </Space>
</template>
```

## 图标 (icon)

通过 `#icon` 插槽添加图标，使用 `v-model:checked` 同步选择状态；支持点击与空格键。

### icon.vue

```vue
<script setup lang="ts">
import { LinkedinOutlined, TwitterOutlined, YoutubeOutlined } from '@apollo-design/icons';
import { CheckableTag, Space } from '@apollo-design/ui';
import { ref } from 'vue';

const checked = ref([true, false, false]);
const icons = [TwitterOutlined, YoutubeOutlined, LinkedinOutlined];
const colors = ['geekblue', 'green', 'purple'];
</script>

<template>
  <Space wrap>
    <CheckableTag v-for="(item, i) in icons" :key="i" v-model:checked="checked[i]">
      <template #icon><component :is="item" aria-hidden="true" /></template>
      {{ colors[i] }}
    </CheckableTag>
  </Space>
</template>
```

## 状态点 (status)

状态色（success / processing / warning / error）× 三 variant。

### status.vue

```vue
<script setup lang="ts">
import {
  CheckCircleOutlined,
  ClockCircleOutlined,
  CloseCircleOutlined,
  ExclamationCircleOutlined,
  SyncOutlined,
} from '@apollo-design/icons';
import { Space, Tag } from '@apollo-design/ui';

const variants = ['filled', 'solid', 'outlined'] as const;
const presets = ['success', 'processing', 'warning', 'error', 'default'] as const;
const iconMap = {
  success: CheckCircleOutlined,
  processing: SyncOutlined,
  warning: ExclamationCircleOutlined,
  error: CloseCircleOutlined,
  default: ClockCircleOutlined,
};
</script>

<template>
  <div v-for="variant in variants" :key="variant">
    <p>Status ({{ variant }})</p>
    <Space wrap>
    <Tag v-for="s in presets" :key="s" :color="s" :variant="variant">
      <template #icon><component :is="iconMap[s]" aria-hidden="true" /></template>
      {{ s }}
    </Tag>
    </Space>
  </div>
</template>
```

## 自定义语义结构的样式和类 (style-class)

通过 `classNames` / `styles` 配置 root、icon、content、close 四个语义区域；原生 `style` 最后覆盖根样式。

### style-class.vue

```vue
<script setup lang="ts">
import { CheckCircleOutlined } from '@apollo-design/icons';
import { Tag, type TagSemanticClassNames, type TagSemanticStyles } from '@apollo-design/ui';

const classNames: TagSemanticClassNames = {
  root: 'demo-tag-root',
  icon: 'demo-tag-icon',
  content: 'demo-tag-content',
  close: 'demo-tag-close',
};
const styles: TagSemanticStyles = {
  root: { padding: '2px 6px', borderRadius: '4px' },
  icon: { fontSize: '14px' },
  content: { fontWeight: 600 },
  close: { marginInlineStart: '8px' },
};
</script>
<template>
  <Tag :class-names="classNames" :styles="styles" :style="[{ paddingInline: '10px' }]" closable>
    <template #icon><CheckCircleOutlined aria-hidden="true" /></template>
    Tag with semantic slots
  </Tag>
</template>
<style scoped>
.demo-tag-root { border-color: var(--apollo-color-primary); }
</style>
```

## 关闭与重置 (animation)

通过父级状态卸载关闭的标签，Reset 重新挂载。Tag 自身默认关闭保留 DOM 并以 `-hidden` 隐藏；此 Demo 不宣称关闭过渡动画。

### animation.vue

```vue
<script setup lang="ts">
import { Button, Tag } from '@apollo-design/ui';
import { ref } from 'vue';

const visible = ref(true);
</script>

<template>
  <Tag v-if="visible" closable :style="{ marginInlineEnd: '8px' }" @close="visible = false"
    >Tag 1</Tag
  >
  <Button @click="visible = true">Reset</Button>
</template>
```

## 组件 Token (component-token)

通过 `ConfigProvider.theme.components.Tag` 配置三个已有组件 Token；切换按钮演示配置即时更新。显式文字色应与实际背景配对。

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, Tag } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const alternate = ref(false);
const theme = computed(() => ({
  // A dark solid surface pairs with the explicit light solid foreground.
  token: { green: alternate.value ? '#304b80' : '#155a32' },
  components: {
    Tag: alternate.value
      ? { defaultBg: '#e5e9ff', defaultColor: '#1b2559', solidTextColor: '#ffffff' }
      : { defaultBg: '#fff7e6', defaultColor: '#5c3100', solidTextColor: '#fffbe6' },
  },
}));
</script>
<template>
  <Button @click="alternate = !alternate">Switch component tokens</Button>
  <ConfigProvider :theme="theme">
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-block-start: 8px">
      <Tag>Default</Tag><Tag>Another</Tag><Tag color="blue">Blue</Tag>
      <Tag color="green" variant="solid">Solid</Tag><Tag variant="outlined">Outlined</Tag>
    </div>
  </ConfigProvider>
</template>
```

---

# TimePicker

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/time-picker


输入或选择单个时间，使用 `TimeRangePicker` 选择时间区间。

> 2026-10-30 当前契约：两种入口均固定为时间轴。支持 `v-model:value`、`v-model:open`、`v-model:pickerValue`；移除无效的 `mode/defaultMode/update:mode` 声明。动态内容使用原生具名槽，通知使用 emits，DOM 句柄可为 null。

## 代码演示

见 [demo](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/time-picker/demo) 的 16 个实际场景。

## API

| 参数 | 说明 | 默认值 |
|---|---|---|
| value / defaultValue | Dayjs 时间值；单值可为 null，区间是两个端点 | — |
| open / defaultOpen | 当前开合 / 非受控初始开合 | — |
| pickerValue / defaultPickerValue | 面板浏览时间 / 初始浏览时间 | — |
| defaultOpenValue | 空值时的时间面板模板，不直接提交为值 | — |
| format | 格式串、格式函数或掩码格式；默认显示时、分、秒 | `HH:mm:ss` |
| use12Hours | 显示上下午列 | `false` |
| showHour / showMinute / showSecond / showMillisecond | 当前显示的时间列，未指定时结合 format 推导 | — |
| hourStep / minuteStep / secondStep / millisecondStep | 档位步长 | `1` |
| disabledTime | 当前时间的禁用档位；范围版另收 range 与 `{ from }` | — |
| hideDisabledOptions | 隐藏禁用档位 | `false` |
| needConfirm | 显式确认后提交；false 时离开面板提交 | `true` |
| changeOnScroll | 滚动停止 300ms 后选中最近的可用档位 | `false` |
| inputReadOnly | 禁止键入，保留面板鼠标与键盘选择 | `false` |
| allowClear | 清除按钮，支持 `{ clearIcon }` | `true` |
| disabled / size / status / variant | 禁用、尺寸、校验状态与变体 | variant 为 `outlined` |
| classNames / styles | 当前语义类名/样式，支持函数形态 | — |
| prefix / suffixIcon / clearIcon | 静态装饰内容，也可用同名槽 | 默认后缀为时钟 |
| placeholder / locale | 提示与当前语言配置 | `Select time` |
| presets | 预设时间；value 支持按交互时刻懒求值 | — |

`TimeRangePicker` 另支持 `separator`、`allowEmpty` 与两端的 disabled 配置。它不提供日期导航、多选标签或面板粒度切换。

`id/name/required/autoComplete/autoFocus/tabIndex` 和 `aria-*` 绑定实际输入框；`class/style/data-*` 绑定根。区间 id 字符串只绑定起点，`{ start, end }` 分别绑定两端。实例暴露 `nativeElement/focus/blur`，区间另有 `startInput/endInput`，元素在挂载前和卸载后为 null。

## 事件与插槽

`change/update:value`、`openChange/update:open`、`pickerValueChange/update:pickerValue` 同时通知语义变化与模型提案。受控父级拒绝提案后不会写入隐藏值，撤控保留最后接受值。还有 `calendarChange/ok/clear/focus/blur/invalid/panelChange`；单值另有 `select`。`keydown` 只收到一个原生 KeyboardEvent，`preventDefault()` 可取消内部行为。

单值支持 `prefix/suffixIcon/clearIcon/panelRender/extraFooter/cellRender/presetRender` 七个槽，范围版再加 `separator`。其中 cellRender 收 `{ current, info }`，panelRender 收 `{ originPanel }`，extraFooter 收 `{ mode }`；显式空槽保持为空，槽增删即时生效。旧渲染函数 props 和 addon 已移除。

只读输入按 ArrowDown 进入面板，方向键在可用档位间导航，Enter/Space 选值，Escape 返回原输入。默认确认制下可继续到 OK 按钮确认。

## 配置与样式

两种 Time 入口都读取当前 `components.timePicker` 的语义配置、root class/style、variant、图标与 separator。输入提示读取当前 `locale.TimePicker`，本地 placeholder 与 locale 中的明确值优先。`datePicker/rangePicker` 配置不会泄漏进来。普通 Date Range 仍读取 `rangePicker` 配置。

TimePicker 复用 DatePicker 的静态 CSS 和主题变量，没有独立 Component Token、样式表或 PurePanel。`popupClassName/popupStyle/bordered/dropdownClassName` 保留已声明的废弃入口，优先使用语义样式与 variant。

`TimePickerWithRange.RangePicker` 与具名 `TimeRangePicker` 指向同一组件。


## 基本 (basic)

点击 `TimePicker`，然后可以在浮层中选择或者输入某一时间。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo。
//
// ⚠️ 上游还传了 `defaultOpenValue`（把面板锚定到 `00:00:00`）—— 本仓的 `date-picker`
//    目前**忽略**它（README §5 第 7 条），所以这里刻意不写：写了也不会生效，
//    只会让 demo 显得在演示一个本仓没实现的能力。

import type { TimePickerEmits } from '@apollo-design/ui';
import { TimePicker } from '@apollo-design/ui';

const onChange: TimePickerEmits['change'] = (time, timeString) => {
  console.log(time, timeString);
};
</script>

<template>
  <TimePicker @change="onChange" />
</template>
```

## 附加内容 (addon)

通过原生 `#extraFooter` 插槽在面板底部添加内容；旧 `addon` 与渲染函数 prop 已移除。

### addon.vue

```vue
<script setup lang="ts">
// The native extraFooter slot can close the controlled popup.
import { Button, TimePicker } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
</script>

<template>
  <TimePicker v-model:open="open">
    <template #extraFooter>
      <Button size="small" type="primary" @click="open = false">OK</Button>
    </template>
  </TimePicker>
</template>
```

## 滚动即选 (change-on-scroll)

滚动时间列即改变值（`changeOnScroll`），配合 `needConfirm={false}` 立即提交。

### change-on-scroll.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 change-on-scroll demo。

import type { TimePickerEmits } from '@apollo-design/ui';
import { TimePicker } from '@apollo-design/ui';

const onChange: TimePickerEmits['change'] = (time, timeString) => {
  console.log(time, timeString);
};
</script>

<template>
  <TimePicker :change-on-scroll="true" :need-confirm="false" @change="onChange" />
</template>
```

## 自定义浮层样式 (colored-popup)

通过 `classNames.popup.root` 给浮层根加类名。

### colored-popup.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 colored-popup demo。

import type { TimePickerEmits } from '@apollo-design/ui';
import { TimePicker } from '@apollo-design/ui';

const onChange: TimePickerEmits['change'] = (time, timeString) => {
  console.log(time, timeString);
};

const classNames = { popup: { root: 'myCustomClassName' } };
</script>

<template>
  <TimePicker :class-names="classNames" @change="onChange" />
</template>
```

## 禁用 (disabled)

禁用状态。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 disabled demo。
import { TimePicker } from '@apollo-design/ui';
import dayjs from 'dayjs';

const value = dayjs('12:08:23', 'HH:mm:ss');
</script>

<template>
  <TimePicker :default-value="value" disabled />
</template>
```

## 隐藏列 (hide-column)

用 `format` 控制显示哪几列（`HH:mm` ⇒ 只有时与分）。

### hide-column.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 hide-column demo。
import { TimePicker } from '@apollo-design/ui';
import dayjs from 'dayjs';

const format = 'HH:mm';
const value = dayjs('12:08', format);
</script>

<template>
  <TimePicker :default-value="value" :format="format" />
</template>
```

## 需要确认 (need-confirm)

`needConfirm` ⇒ 需要点「确定」才提交。

### need-confirm.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 need-confirm demo。

import type { TimePickerEmits } from '@apollo-design/ui';
import { TimePicker } from '@apollo-design/ui';

const onChange: TimePickerEmits['change'] = (time, timeString) => {
  console.log(time, timeString);
};
</script>

<template>
  <TimePicker :need-confirm="true" @change="onChange" />
</template>
```

## 范围选择 (range-picker)

`TimeRangePicker` 选择一段时间。

### range-picker.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 range-picker demo。
//
// ⚠️ 上游写的是 `TimePicker.RangePicker`（静态成员）；本仓两种写法都支持，
//    这里用具名导出 `TimeRangePicker`（类型可见性更好）。
import { TimeRangePicker } from '@apollo-design/ui';
import dayjs from 'dayjs';

const format = 'HH:mm:ss';
const startTime = dayjs('12:08:23', format);
const endTime = dayjs('12:08:23', format);
</script>

<template>
  <TimeRangePicker :default-value="[startTime, endTime]" :format="format" />
</template>
```

## 不同尺寸 (size)

三种尺寸：`large` / 默认 / `small`。

### size.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 size demo。
import { Space, TimePicker } from '@apollo-design/ui';
import dayjs from 'dayjs';

const value = dayjs('12:08:23', 'HH:mm:ss');
</script>

<template>
  <Space wrap>
    <TimePicker :default-value="value" size="large" />
    <TimePicker :default-value="value" />
    <TimePicker :default-value="value" size="small" />
  </Space>
</template>
```

## 校验状态 (status)

`status` 标记校验状态（`error` / `warning`），单值与范围都支持。

### status.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 status demo。
import { Space, TimePicker, TimeRangePicker } from '@apollo-design/ui';
</script>

<template>
  <Space vertical>
    <TimePicker status="error" />
    <TimePicker status="warning" />
    <TimeRangePicker status="error" />
    <TimeRangePicker status="warning" />
  </Space>
</template>
```

## 语义化结构样式 (style-class)

通过 `classNames` 与 `styles` 自定义[语义化结构](#semantic-dom)样式；`styles` 支持对象与函数两种形态。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo。
//
// ⚠️ 上游的 `classNames` 来自 `antd-style` 的 `createStyles`；本仓零运行时样式方案，
//    直接给等价的静态类名（`demo-tp-root` 由本文件底部的作用域样式提供）。

import type { TimePickerProps } from '@apollo-design/ui';
import { Flex, TimePicker } from '@apollo-design/ui';

const classNames = { root: 'demo-tp-root' };

/** 对象形态。 */
const stylesObject: TimePickerProps['styles'] = {
  root: { borderColor: '#d9d9d9' },
};

/** 函数形态：按 `info.props.size` 分支。 */
const stylesFn: TimePickerProps['styles'] = (info) => {
  if (info.props.size === 'large') {
    return {
      root: { borderColor: '#722ed1' },
      suffix: { color: '#722ed1' },
      popup: { container: { border: '1px solid #722ed1', borderRadius: 8 } },
    };
  }
  return {};
};
</script>

<template>
  <Flex vertical gap="medium">
    <TimePicker :class-names="classNames" :styles="stylesObject" placeholder="Object" />
    <TimePicker
      :class-names="classNames"
      :styles="stylesFn"
      placeholder="Function"
      size="large"
    />
  </Flex>
</template>

<style scoped>
.demo-tp-root {
  width: 150px;
  border: 1px solid var(--apollo-color-primary);
}
</style>
```

## 前后缀 (suffix)

`suffixIcon` 与 `prefix` 自定义前后缀；范围版也支持 `prefix`。

### suffix.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 suffix demo。
import { SmileOutlined } from '@apollo-design/icons';
import type { TimePickerEmits } from '@apollo-design/ui';
import { Space, TimePicker, TimeRangePicker } from '@apollo-design/ui';

const onChange: TimePickerEmits['change'] = (time, timeString) => {
  console.log(time, timeString);
};
</script>

<template>
  <Space vertical :size="12">
    <TimePicker @change="onChange">
      <template #suffixIcon><SmileOutlined /></template>
    </TimePicker>
    <TimePicker>
      <template #prefix><SmileOutlined /></template>
    </TimePicker>
    <TimeRangePicker>
      <template #prefix><SmileOutlined /></template>
    </TimeRangePicker>
  </Space>
</template>
```

## 受控组件 (value)

受控用法：`v-model:value`。

### value.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 value demo。

import type { TimePickerValue } from '@apollo-design/ui';
import { TimePicker } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TimePickerValue>(null);
</script>

<template>
  <TimePicker v-model:value="value" />
</template>
```

## 变体 (variant)

四种视觉变体：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

### variant.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 variant demo。
import { Flex, TimePicker, TimeRangePicker } from '@apollo-design/ui';
</script>

<template>
  <Flex vertical :gap="12">
    <Flex wrap :gap="8">
      <TimePicker placeholder="Outlined" />
      <TimeRangePicker :placeholder="['Outlined Start', 'Outlined End']" />
    </Flex>
    <Flex wrap :gap="8">
      <TimePicker variant="filled" placeholder="Filled" />
      <TimeRangePicker variant="filled" :placeholder="['Filled Start', 'Filled End']" />
    </Flex>
    <Flex wrap :gap="8">
      <TimePicker variant="borderless" placeholder="Borderless" />
      <TimeRangePicker variant="borderless" :placeholder="['Borderless Start', 'Borderless End']" />
    </Flex>
    <Flex wrap :gap="8">
      <TimePicker variant="underlined" placeholder="Underlined" />
      <TimeRangePicker variant="underlined" :placeholder="['Underlined Start', 'Underlined End']" />
    </Flex>
  </Flex>
</template>
```

## 12 小时制 (12hours)

通过 `use12Hours` 显示上下午列，配合 `format` 的 `A` / `a` 标记控制输入框的时间文案。

### 12hours.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 12hours demo：use12Hours 增加上下午列，format 决定输入框展示形态。
import type { TimePickerEmits } from '@apollo-design/ui';
import { Space, Text, TimePicker } from '@apollo-design/ui';
import { ref } from 'vue';

const selected = ref('（未选择）');

const onChange: TimePickerEmits['change'] = (_time, timeString) => {
  selected.value = Array.isArray(timeString)
    ? timeString.join(' ~ ')
    : (timeString ?? '（未选择）');
};
</script>

<template>
  <div>
    <Space wrap>
      <TimePicker use12-hours placeholder="h:mm:ss A" @change="onChange" />
      <TimePicker
        use12-hours
        format="h:mm:ss A"
        placeholder="h:mm:ss A"
        @change="onChange"
      />
      <TimePicker use12-hours format="h:mm a" placeholder="h:mm a" @change="onChange" />
    </Space>
    <div style="margin-top: 8px">
      <Text type="secondary">最近一次选择：{{ selected }}</Text>
    </div>
  </div>
</template>
```

## 步长选项 (interval-options)

`hourStep` / `minuteStep` / `secondStep` 决定面板各列的档位间隔；关闭 `needConfirm` 后滚动即提交。

### interval-options.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 interval-options demo：自定义时/分/秒步长，滚动即预览、无需确认。
import type { TimePickerEmits } from '@apollo-design/ui';
import { Text, TimePicker } from '@apollo-design/ui';
import { ref } from 'vue';

const selected = ref('（未选择）');

const onChange: TimePickerEmits['change'] = (_time, timeString) => {
  selected.value = Array.isArray(timeString)
    ? timeString.join(' ~ ')
    : (timeString ?? '（未选择）');
};
</script>

<template>
  <div>
    <TimePicker
      :hour-step="1"
      :minute-step="15"
      :second-step="10"
      :need-confirm="false"
      change-on-scroll
      placeholder="每 15 分钟一档"
      @change="onChange"
    />
    <div style="margin-top: 8px">
      <Text type="secondary">最近一次选择：{{ selected }}</Text>
    </div>
  </div>
</template>
```

---

# Timeline

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/timeline


按顺序展示事件、状态和完整说明，支持纵向与横向。根是原生 `<ol>`，每项是 `<li>`。Timeline 组合内部 Steps 渲染器；组件没有选中状态或业务事件。

## 代码演示

`demo/` 中十五对示例覆盖基础内容、变体、末端排布、标题栏、横向和交错布局、加载、旧 pending 数据、自定义图标、长文本、标题、语义样式、原生插槽及动态组件 Token。

## API

### Timeline

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| items | 有序条目数据；模板富内容使用原生条目槽 | `TimelineItemType[]` | — |
| mode | 条目排布；旧 left/right 归一为 start/end | `'start' \| 'end' \| 'alternate' \| 'left' \| 'right'` | `'start'` |
| orientation | 显式方向，在所有视口宽度下保持 | `'horizontal' \| 'vertical'` | `'vertical'` |
| titleSpan | 标题栏：数字按 24 栅格，字符串为 CSS 长度/百分比 | `number \| string` | — |
| variant | 节点变体 | `'filled' \| 'outlined'` | `'outlined'` |
| reverse | 反转显示顺序；连线状态改跟当前条目 | `boolean` | `false` |
| pending | 已废弃，改在 items 中追加加载项。false/null/undefined 关闭；0/空字符串仍创建 pending 项；true 只显示指示器 | `VNodeChild` | — |
| pendingDot | 已废弃，旧 pending 合成项的自定义图标；改用 items[].icon | `VNodeChild` | — |
| classNames | 语义类名对象，或读取当前 `{ props }` 的函数 | `TimelineSemanticValue<TimelineSemanticClassNames>` | — |
| styles | 语义样式对象，或读取当前 `{ props }` 的函数 | `TimelineSemanticValue<TimelineSemanticStyles>` | — |
| prefixCls | DOM 类名前缀；任意前缀需配套静态 CSS | `string` | `apollo-timeline` |

纵向中任一当前标题非空时启用两栏布局。显式 mode="alternate" 也启用该布局，并按源条目奇偶分配排布侧。反转改变显示顺序和槽索引，保留每个源条目的排布侧。显式 alternate 模式忽略 titleSpan。

横向交错布局中，长标题和正文在各自栏内换行；共享自然高度行保持横轴对齐，并随内容增长。wrapper、section、header 仍是可设置样式的真实盒子。无标题纵向列表同样消费 itemPaddingBottom，默认20px，紧凑算法为10px。

### 条目数据

| 字段 | 说明 | 类型 |
| --- | --- | --- |
| key | 替换/重排时的稳定条目标识 | `string \| number` |
| title / content / icon | 完整 Vue 内容，支持 0、Fragment 和组件；显式 false/空图标覆盖默认加载图标 | `VNodeChild` |
| color | blue/red/green/gray 使用预设类；其他颜色写入本项 dot-color CSS 变量 | `string` |
| loading | process 状态；icon 和 dot 均 absent/null 时使用默认加载图标 | `boolean` |
| placement | 排布侧；未给出时从 mode 推导 | `'start' \| 'end'` |
| className / style | 项根类名与内联样式 | `string` / `CSSProperties` |
| classNames / styles | 项级区域：root、wrapper、header、title、section、content、icon、rail | 语义对象 |
| label / children / dot | 已废弃的 title/content/icon 数据别名；仅在对应新字段 nullish 时回退 | `VNodeChild` |
| position | 已废弃的 placement 别名；left/right 归一为 start/end，显式 placement 优先 | `'left' \| 'right' \| 'start' \| 'end'` |

项根样式按组件 styles.item → 项 styles.root → 项 style 合并。其余区域先合并组件语义样式，再合并本项语义样式。没有 subtitle 区域。原生条目槽使用同一内容宿主和样式落点。

### 内容插槽

| 名称 | 作用域 | 说明 |
| --- | --- | --- |
| itemTitle | `{ item, index }: TimelineItemSlotProps` | 条目标题 |
| itemContent | `{ item, index }: TimelineItemSlotProps` | 条目正文 |
| itemIcon | `{ item, index }: TimelineItemSlotProps` | 条目图标 |

item 是当前原始数据项；index 是反转后的显示索引，含旧 pending 节点占位。槽存在就覆盖对应数据及别名，有意为空也覆盖；移除槽恢复数据。SSR 和水合中同样渲染。pending 合成项没有源数据作用域。默认槽不注册条目；开发版已移除 Timeline.Item / TimelineItemComponent，见[插槽迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/timeline-item-slots.md)。

### 原生 attrs、事件与 ref

原生 class/style、id、tabindex、ARIA 属性和 DOM 监听器落到有序列表根。原生根 style 覆盖同名语义 root 样式；class 支持 Vue 字符串/数组/对象，style 支持字符串/数组/对象。原生 @change 接收冒泡的 DOM Event，不会启用可选中的条目。@click 和事件修饰符遵循 Vue DOM 语义。Timeline 没有 emits 或 v-model。

ref 暴露 `{ nativeElement: HTMLElement | null }`，挂载后为当前 `<ol>`。数据、布局和 Provider 更新保持元素身份；卸载后父级 ref 清空。替换或重排数据时为条目提供显式 key，以保留输入节点和值。

## 主题

ConfigProvider 的 components.timeline 提供当前 className/style/classNames/styles 默认值。direction、主题算法和嵌套组件 Token 均响应式更新，多实例作用域隔离。根样式优先级为当前主题 → Provider/组件语义 root 样式 → 原生 style。

| 组件 Token | 说明 | 默认值 |
| --- | --- | --- |
| tailColor | 连线颜色 | colorSplit |
| tailWidth | 连线宽度 | lineWidthBold |
| dotBorderWidth | 节点边框宽度 | lineWidthBold |
| itemPaddingBottom | 条目底部间距 | padding * 1.25 |
| dotSize | 自定义节点大小 | undefined；保留内部 Steps 大小回退 |
| dotBg | 自定义节点背景 | undefined；保留内部 Steps 背景回退 |

在 ConfigProvider 设置 `:theme="{ components: { Timeline: { dotSize: 14, tailWidth: 3 } } }"`，也可用根 CSS 变量，如 `--apollo-timeline-dot-size: 14px`。尺寸接受有限非负数字并转为 px，宽度/大小 Token 还可接受 CSS 长度字符串。移除可选 dot Token 后恢复回退值。主题更新不生成运行时样式表。

原生事件、排布侧、零内容、ref 与 Token 修正见[当前契约迁移](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/timeline-contracts.md)。


## 基本 (basic)

基础的时间轴 —— 只给 `content`（无 `title` ⇒ 纵向**不**交错）。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `basic` demo。
import { Timeline } from '@apollo-design/ui';

const items = [
  { content: 'Create a services site 2015-09-01' },
  { content: 'Solve initial network problems 2015-09-01' },
  { content: 'Technical testing 2015-09-01' },
  { content: 'Network problems being solved 2015-09-01' },
];
</script>

<template>
  <Timeline :items="items" />
</template>
```

## 变体 (variant)

`variant="filled"` 与默认的 `"outlined"` 是两种视觉变体（透传给内部的 `Steps`）。

### variant.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `variant` demo。
import { Timeline } from '@apollo-design/ui';

const items = [
  { content: 'Create a services site 2015-09-01' },
  { content: 'Solve initial network problems 2015-09-01' },
  { content: 'Technical testing 2015-09-01' },
  { content: 'Network problems being solved 2015-09-01' },
];
</script>

<template>
  <Timeline variant="filled" :items="items" />
</template>
```

## 右侧时间轴 (end)

`mode="end"` 把节点靠右；`icon` + `color` 可以自定义某一项的节点。

### end.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `end` demo。

import { ClockCircleOutlined } from '@apollo-design/icons';
import { Timeline } from '@apollo-design/ui';
import { h } from 'vue';

const items = [
  { content: 'Create a services site 2015-09-01' },
  { content: 'Solve initial network problems 2015-09-01' },
  {
    icon: h(ClockCircleOutlined),
    color: 'red',
    content: 'Technical testing 2015-09-01',
  },
  { content: 'Network problems being solved 2015-09-01' },
];
</script>

<template>
  <Timeline mode="end" :items="items" />
</template>
```

## 标题宽度 (title-span)

`titleSpan` 控制标题栏的占比：数字按 **24 栅格**、字符串按 **CSS 长度**。

上方宽度说明使用强调文本，避免在嵌入文档时添加跳级标题。

### title-span.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `title-span` demo。
import { Flex, Text, Timeline } from '@apollo-design/ui';

const items = [
  { title: '05:10', content: 'Create a services' },
  { title: '09:03', content: 'Solve initial network problems' },
  { content: 'Technical testing' },
  { title: '11:28', content: 'Network problems being solved' },
];
</script>

<template>
  <Flex vertical :gap="16">
    <Text strong :style="{ fontSize: 'var(--apollo-font-size-lg)' }">titleSpan = 100px</Text>
    <Timeline :items="items" title-span="100px" />
    <Text strong :style="{ fontSize: 'var(--apollo-font-size-lg)' }">titleSpan = 25%</Text>
    <Timeline :items="items" title-span="25%" />
    <Text strong :style="{ fontSize: 'var(--apollo-font-size-lg)' }">titleSpan = 18, mode = end</Text>
    <Timeline :items="items" :title-span="18" mode="end" />
  </Flex>
</template>
```

## 水平时间轴 (horizontal)

`orientation="horizontal"` 是**另一套绝对定位布局**（`mode` 的三种取值各有形态）。

### horizontal.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `horizontal` demo。
import { Divider, Flex, Timeline } from '@apollo-design/ui';

const items = [
  { content: 'Init' },
  { content: 'Start' },
  { content: 'Pending' },
  { content: 'Complete' },
];
</script>

<template>
  <Flex vertical>
    <Timeline :items="items" orientation="horizontal" mode="start" />
    <Divider />
    <Timeline :items="items" orientation="horizontal" mode="end" />
    <Divider />
    <Timeline :items="items" orientation="horizontal" mode="alternate" />
  </Flex>
</template>
```

## 交替展现 (alternate)

`mode="alternate"` 让内容**左右交替**（按项序号奇偶）。

### alternate.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `alternate` demo。

import { ClockCircleOutlined } from '@apollo-design/icons';
import { Timeline } from '@apollo-design/ui';
import { h } from 'vue';

const items = [
  { content: 'Create a services site 2015-09-01' },
  { content: 'Solve initial network problems 2015-09-01', color: 'green' },
  {
    icon: h(ClockCircleOutlined, { style: { fontSize: '16px' } }),
    content:
      'Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.',
  },
  { color: 'red', content: 'Network problems being solved 2015-09-01' },
  { content: 'Create a services site 2015-09-01' },
  {
    icon: h(ClockCircleOutlined, { style: { fontSize: '16px' } }),
    content: 'Technical testing 2015-09-01',
  },
];
</script>

<template>
  <Timeline mode="alternate" :items="items" />
</template>
```

## 反转 + 进行中 (pending)

`reverse` 反转项顺序（⚠️ 连线的状态也随之改跟当前项）；`loading: true` 的项是「进行中」。

### pending.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `pending` demo。
import { Button, Flex, Timeline } from '@apollo-design/ui';
import { ref } from 'vue';

const reverse = ref(false);
const items = [
  { content: 'Create a services site 2015-09-01' },
  { content: 'Solve initial network problems 2015-09-01' },
  { content: 'Technical testing 2015-09-01' },
  { loading: true, content: 'Recording...' },
];
</script>

<template>
  <Flex vertical :gap="16" align="flex-start">
    <Timeline :reverse="reverse" :items="items" />
    <Button type="primary" @click="reverse = !reverse">Toggle Reverse</Button>
  </Flex>
</template>
```

## 进行中（旧 API） (pending-legacy)

⚠️ **已废弃**的 `pending` / `pendingDot` —— 现在请直接在 `items` 里加一项。

### pending-legacy.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `pending-legacy` demo。
import { Flex, Timeline } from '@apollo-design/ui';

const items = [{ content: 'Create a services site 2015-09-01' }];
</script>

<template>
  <Flex vertical :gap="16" align="flex-start">
    <Timeline pending="Recording..." :items="items" />
    <Timeline pending="Recording..." pending-dot="🔴" :items="items" />
  </Flex>
</template>
```

## 自定义节点 (custom)

`icon` 自定义节点；自定义 `fontSize` 时需要自己给背景色（否则连线会透出来）。

### custom.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `custom` demo。

import { ClockCircleOutlined } from '@apollo-design/icons';
import { Timeline } from '@apollo-design/ui';
import { h } from 'vue';

const items = [
  { content: 'Create a services site 2015-09-01' },
  { content: 'Solve initial network problems 2015-09-01' },
  {
    icon: h(ClockCircleOutlined, {
      style: { fontSize: '20px', background: 'var(--apollo-color-bg-container)' },
    }),
    color: 'red',
    content: 'Technical testing 2015-09-01',
  },
  { content: 'Network problems being solved 2015-09-01' },
];
</script>

<template>
  <Timeline :items="items" />
</template>
```

## 水平调试 (horizontal-debug)

水平 + 长文本：用 `styles.item` 画一个 1px 的调试描边，看三种 `mode` 的排布。

交错模式按各栏的实际内容扩展上下行，长文换行、横轴保持对齐；移动宽度也保留完整内容。

### horizontal-debug.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `horizontal-debug` demo。
import { Divider, Flex, Timeline } from '@apollo-design/ui';

const longText = 'Long Text '.repeat(5);
const items = [
  { title: longText, content: longText },
  { content: longText },
  { content: longText },
  { title: longText, content: longText },
];
const sharedStyles = { item: { boxShadow: '0 0 1px rgba(255,0,0,0.6)' } };
</script>

<template>
  <Flex vertical>
    <Timeline :items="items" orientation="horizontal" mode="start" :styles="sharedStyles" />
    <Divider />
    <Timeline :items="items" orientation="horizontal" mode="end" :styles="sharedStyles" />
    <Divider />
    <Timeline :items="items" orientation="horizontal" mode="alternate" :styles="sharedStyles" />
  </Flex>
</template>
```

## 带标题 (title)

带 `title` 的项 ⇒ 纵向时**自动进入交错布局**（`layoutAlternate` 的第二条判据）。

### title.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `title` demo。
import { Radio, RadioGroup, Timeline } from '@apollo-design/ui';
import { ref } from 'vue';

const mode = ref<'start' | 'alternate' | 'end'>('start');
const items = [
  { title: '2015-09-01', content: 'Create a services' },
  { title: '2015-09-01 09:12:11', content: 'Solve initial network problems' },
  { content: 'Technical testing' },
  { title: '2015-09-01 09:12:11', content: 'Network problems being solved' },
];
</script>

<template>
  <RadioGroup v-model:value="mode" :style="{ marginBottom: '20px' }">
    <Radio value="start">Start</Radio>
    <Radio value="end">End</Radio>
    <Radio value="alternate">Alternate</Radio>
  </RadioGroup>
  <Timeline :mode="mode" :items="items" />
</template>
```

## 样式与类名 (style-class)

`styles` 支持**函数形态**（按 `info.props` 动态返回）；`classNames.root` 加自定义类。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `style-class` demo。
import { Flex, Timeline } from '@apollo-design/ui';

const items = [
  { title: '2015-09-01', content: 'Create a services site' },
  { title: '2015-09-01 09:12:11', content: 'Solve initial network problems' },
  { content: 'Technical testing' },
];
const classNames = { root: 'demo-timeline-root' };
const styles = { itemIcon: { borderColor: '#1890ff' } };
/** ⚠️ 函数形态：拿到的 `info.props` 是**解析后**的 props。 */
const stylesFn = (info: { props: { orientation?: string } }) =>
  info.props.orientation === 'vertical'
    ? {
        root: { padding: '10px 6px', border: '1px solid #A294F9' },
        itemIcon: { borderColor: '#A294F9' },
      }
    : {};
</script>

<template>
  <Flex vertical :gap="16">
    <Timeline
      :class-names="classNames"
      :items="items"
      orientation="horizontal"
      :styles="styles"
    />
    <Timeline
      :class-names="classNames"
      :items="items"
      orientation="vertical"
      :styles="stylesFn"
    />
  </Flex>
</template>
```

## 语义化结构 (semantic)

**项级**语义化槽（`styles.root` / `rail` / `content`）—— 注意它在 `items[i].styles` 上，不是根上的。

淡化正文仍保持默认与暗色主题下的文字对比度。

### semantic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `semantic` demo。
import { Timeline } from '@apollo-design/ui';

const dashed = { borderStyle: 'dashed' };
const items = [
  { content: 'Create a services site 2015-09-01' },
  {
    content: 'Solve initial network problems 2015-09-01',
    styles: { root: { height: '100px' }, rail: dashed },
  },
  {
    content: '...for a long time...',
    styles: { root: { height: '100px' }, rail: dashed, content: { opacity: 0.7 } },
  },
  { content: 'Technical testing 2015-09-01' },
  { content: 'Network problems being solved 2015-09-01' },
];
</script>

<template>
  <Timeline :items="items" />
</template>
```

## 原生条目插槽 (native-slots)

itemTitle / itemContent / itemIcon 使用单个 { item, index } 对象。显式空槽覆盖数据回退；移除槽恢复回退。输入后反转或更新数据，观察 keyed 条目状态保持。

### native-slots.vue

```vue
<script setup lang="ts">
import { Button, Input, Timeline } from '@apollo-design/ui';
import { ref } from 'vue';

const custom = ref(true);
const empty = ref(false);
const reverse = ref(false);
const items = ref([
  { key: 'created', title: '2026-10-24', content: 'Created' },
  { key: 'reviewed', title: '2026-10-25', content: 'Reviewed' },
]);
const update = () => {
  items.value = items.value.map((item) => ({ ...item, content: `${item.content}!` }));
};
</script>

<template>
  <div style="display: flex; gap: 8px; margin-bottom: 16px; flex-wrap: wrap">
    <Button @click="custom = !custom">Toggle item slots</Button>
    <Button @click="empty = !empty">Toggle empty content</Button>
    <Button @click="reverse = !reverse">Reverse items</Button>
    <Button @click="update">Update item data</Button>
  </div>
  <Timeline :items="items" :reverse="reverse">
    <template v-if="custom" #itemTitle="{ item }">
      <time v-if="!empty" :datetime="String(item.title)">{{ item.title }}</time>
    </template>
    <template v-if="custom" #itemContent="{ item, index }">
      <div v-if="!empty">
        <strong>{{ item.content }} · {{ index }}</strong>
        <Input :aria-label="`Note ${item.key}`" placeholder="Type, then reverse or update" />
      </div>
    </template>
    <template v-if="custom" #itemIcon="{ index }">
      <span v-if="!empty" aria-hidden="true">{{ index + 1 }}</span>
    </template>
  </Timeline>
</template>
```

## 组件 Token (component-token)

通过当前 ConfigProvider 的 `theme.components.Timeline` 动态覆盖六个组件 Token；切换后恢复默认大小、背景和间距。也支持根 `--apollo-timeline-*` CSS 变量。

Use current `theme.components.Timeline` to update all six component tokens. Toggle to restore the default node fallback, background and spacing. Root CSS variables are also supported.

### component-token.vue

```vue
<script setup lang="ts">
import type { TimelineItemType } from '@apollo-design/ui';
import { Button, ConfigProvider, Timeline } from '@apollo-design/ui';
import { ref } from 'vue';

const custom = ref(true);

const items: TimelineItemType[] = [
  { content: 'Create a services site 2015-09-01' },
  { content: 'Solve initial network problems 2015-09-01', color: 'blue' },
  { content: 'Technical testing 2015-09-01', color: 'green' },
  { content: 'Network problems being solved 2015-09-01' },
];
</script>

<template>
  <Button style="margin-bottom: 16px" @click="custom = !custom">Toggle component tokens</Button>
  <ConfigProvider :theme="{ components: { Timeline: custom ? {
    tailColor: '#91caff', tailWidth: 3, dotSize: 14, dotBg: '#e6f4ff',
    dotBorderWidth: 3, itemPaddingBottom: 28,
  } : {} } }">
    <Timeline :items="items" />
  </ConfigProvider>
</template>
```

---

# Tooltip

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/tooltip


简单的文字提示气泡框。

## 何时使用

- 鼠标移入则显示提示，移出消失，不针对复杂交互。
- 用轻量的文字提示代替貼心的复杂说明。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/tooltip/demo)（15 个，覆盖 antd 的主要用户场景；Segmented/Select
未落地 ⇒ 原生 select 替换，见各文件头）。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 提示内容数据（`0` 合法）；模板富内容使用 `#title` | `VNodeChild` | — |
| open / defaultOpen | 受控开合（`v-model:open` 等价）/ 非受控初值 | `boolean` | `false` |
| trigger | 触发动作 | `'hover' \| 'click' \| 'focus' \| 'contextMenu' \| 数组` | `'hover'` |
| placement | 位置（12 个） | `TooltipPlacement` | `'top'` |
| arrow | 箭头（`false` 隐藏 / `{ pointAtCenter }` 指中心） | `boolean \| object` | `true` |
| color | 预设色或自定义 CSS 颜色 | `string` | — |
| autoAdjustOverflow | 溢出自动调整 | `boolean \| AdjustOverflow` | `true` |
| mouseEnterDelay / mouseLeaveDelay | 延迟（秒） | `number` | `0.1` |
| getPopupContainer / getTooltipContainer | 挂载容器 | `(node) => HTMLElement` | `body` |
| openClassName | 开启时触发元素追加的类名 | `string` | `` `{p}-open` `` |
| destroyOnHidden | 关闭后卸载 portal | `boolean` | `false` |
| destroyTooltipOnHide | ⚠️ 已废弃，用 `destroyOnHidden` | `boolean \| object` | — |
| motion | 动画（仅 motionName 可覆盖） | `{ motionName?: string }` | `apollo-zoom-big-fast` |
| zIndex | 层级（未传走 useZIndex 层叠体系） | `number` | `1070` |
| id | 提示内容 id，供触发元素的 aria-describedby 引用 | `string` | 自动生成 |
| fresh / forceRender / disabled | 关闭时更新内容 / 强制挂载 / 禁用 | `boolean` | `false` |
| classNames / styles | 语义槽 `root / container / arrow`（含函数式） | — | — |
| overlayStyle / overlayInnerStyle / overlayClassName | ⚠️ 已废弃 | — | — |

### 事件

| 名称 | 载荷 | 说明 |
|---|---|---|
| update:open | `boolean` | `v-model:open` 的状态提议 |
| openChange | `boolean` | 与 update:open 同时通知，受控值由父级接受 |
| afterOpenChange | `boolean` | 本次开合动画完成 |
| popupClick | `MouseEvent` | 点击提示内容的原始事件 |

事件使用 Vue emits，支持 `@open-change.once` 等修饰符。`h()` 使用 `onOpenChange`、`onAfterOpenChange` 和 `onPopupClick`；空内容仍遵循下述抑制规则。

### 插槽

| 名称 | 说明 |
|---|---|
| default | 触发元素（组件也可；事件与 ref 需透传到根元素） |
| title | 提示内容；存在则覆盖 title prop，空槽不回退 |

`TooltipSlots` 已导出。`TooltipPurePanel` 支持同样的 title 数据与具名槽；条件槽每轮渲染读取。

### 原生 class/style

`Tooltip` 的原生 `class/style` 作用于浮层根；`TooltipPurePanel` 作用于面板根。style 支持字符串、对象及混合数组，优先于 Provider 和语义根样式；移除后恢复当前来源。容器样式使用 `styles.container`，不会从根复制。Tooltip 的其他原生 attrs 和监听器作用于触发元素，触发元素自己的 class/style 写在默认槽子节点上。

最终根样式中的数值 `zIndex`（含 `0` 和数字字符串）同时用于后代浮层层级，覆盖专用 `zIndex` 属性；Provider、`styles.root`、`overlayStyle` 和原生 style 按既有样式顺序合并。条件样式中的 `undefined`、空字符串，以及原生 style 的 `false/null/undefined` 会释放当前覆盖，恢复剩余来源或自动层级。`calc(...)` / `var(...)` 保留 CSS 表达式，但不推导其后代数值层级；该集成边界仍延期。

### 当前主题

`ConfigProvider.theme.components.Tooltip` 支持 `maxWidth`（数字，默认 250px）和 `zIndexPopup`（数字，默认 `zIndexPopupBase + 70`）。替换、撤回和嵌套主题即时更新现有浮层。箭头形状、偏移与定位读取同一份当前 Alias Token；语义样式和原生 CSS 变量覆盖优先。PurePanel 使用当前主题的颜色和箭头，其静态面板保留自然宽度。

### Expose

`forceAlign()`、`nativeElement: HTMLElement | null`、`popupElement: HTMLDivElement | null`（`TooltipRef`）。后两者是当前元素属性；关闭并销毁浮层后 popupElement 为 null。

### 开发版迁移

原 `:after-open-change="handler"` 改为 `@after-open-change="handler"`，对象写法由 `afterOpenChange` 改为 `onAfterOpenChange`。原生 class/style 现在只作用于浮层根；要设置触发元素，请直接写在默认槽元素上。当前开发版直接修正，无兼容分支或弃用期。

## 设计说明

- **trigger 基建**：`_internal/trigger.ts` 组装 overlay + position + portal +
  motion（见 [`docs/analysis/tooltip.md`](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/analysis/tooltip.md) §8）。
- **C8-R2**：`overlay` 与 render-fn `title` 已删除 —— 内容走 `#title` 插槽（slot 优先）。
- **noTitle 抑制**：当前内容为空时，非受控浮层不打开且不发开合回调。受控 `open` 保留调用方状态，`0` 是有效内容；空 `#title` 不回退 prop。
- 与 antd 的已知差异见组件 README。


## 箭头指向中心 (arrow-point-at-center)

`arrow={{ pointAtCenter: true }}` 让箭头始终指向触发元素中心，可对比 `arrow={false}` 的无箭头形态。

### arrow-point-at-center.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `arrow-point-at-center` demo：箭头始终指向触发元素中心。
import { Button, Space, Tooltip } from '@apollo-design/ui';

const placements = [
  'topLeft',
  'top',
  'topRight',
  'left',
  'right',
  'bottomLeft',
  'bottom',
  'bottomRight',
] as const;
</script>

<template>
  <div>
    <Space wrap :size="16">
      <Tooltip
        v-for="placement in placements"
        :key="placement"
        :title="`arrow points at center (${placement})`"
        :placement="placement"
        :arrow="{ pointAtCenter: true }"
      >
        <Button>{{ placement }}</Button>
      </Tooltip>
    </Space>
    <div style="margin-top: 16px">
      <Tooltip title="No arrow" :arrow="false">
        <Button>Compare: no arrow</Button>
      </Tooltip>
    </div>
  </div>
</template>
```

## arrow (arrow)

支持显示、隐藏以及将箭头保持居中定位。

### arrow.vue

```vue
<script setup lang="ts">
import { Button, Select, Space, Tooltip, type TooltipPlacement } from '@apollo-design/ui';
import { ref } from 'vue';

type ArrowMode = 'show' | 'hide' | 'center';
const arrowMode = ref<ArrowMode>('show');
const placement = ref<TooltipPlacement>('topLeft');
const placements: TooltipPlacement[] = [
  'topLeft',
  'top',
  'topRight',
  'leftTop',
  'left',
  'leftBottom',
  'rightTop',
  'right',
  'rightBottom',
  'bottomLeft',
  'bottom',
  'bottomRight',
];
const arrowOptions = [
  { value: 'show', label: 'Show Arrow' },
  { value: 'hide', label: 'Hide Arrow' },
  { value: 'center', label: 'Center Arrow' },
];
const arrowProp = () => {
  if (arrowMode.value === 'hide') return false;
  if (arrowMode.value === 'center') return { pointAtCenter: true };
  return true;
};
</script>

<template>
  <Space wrap :size="12">
    <Select v-model:value="arrowMode" :options="arrowOptions" aria-label="arrow mode" style="width: 160px" />
    <Select v-model:value="placement" :options="placements.map(value => ({ value, label: value }))" aria-label="placement" style="width: 150px" />
    <Tooltip :title="placement" :placement="placement" :arrow="arrowProp()">
      <Button>{{ placement }}</Button>
    </Tooltip>
  </Space>
</template>
```

## auto-adjust-overflow (auto-adjust-overflow)

自动调整溢出。

### auto-adjust-overflow.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/auto-adjust-overflow.tsx（滚动容器内对比 autoAdjustOverflow）

import { Button, Space, Tooltip } from '@apollo-design/ui';
import { onMounted, ref } from 'vue';

const block1 = ref<HTMLDivElement | null>(null);
const block2 = ref<HTMLDivElement | null>(null);

onMounted(() => {
  if (block1.value) block1.value.scrollLeft = (block1.value.clientWidth || 0) * 0.5;
  if (block2.value) block2.value.scrollLeft = (block2.value.clientWidth || 0) * 0.5;
});

const blockStyle: Record<string, string> = {
  overflow: 'auto',
  position: 'relative',
  padding: '24px',
  border: '1px solid var(--apollo-color-border)',
};
const innerStyle: Record<string, string> = {
  width: '200%',
  display: 'flex',
  flexDirection: 'column',
  alignItems: 'center',
  rowGap: '16px',
};
</script>

<template>
  <div style="font-family: sans-serif; display: flex; flex-direction: column; row-gap: 16px">
    <Space wrap>
      <Tooltip placement="left" title="Prompt Text" :get-popup-container="(t: HTMLElement) => t.parentElement as HTMLElement">
        <Button>Adjust automatically</Button>
      </Tooltip>
      <Tooltip placement="left" title="Prompt Text" :auto-adjust-overflow="false" :get-popup-container="(t: HTMLElement) => t.parentElement as HTMLElement">
        <Button>Ignore</Button>
      </Tooltip>
    </Space>
    <div ref="block1" :style="blockStyle">
      <div :style="innerStyle">
        <Tooltip placement="left" title="Prompt Text" :get-popup-container="(t: HTMLElement) => t.parentElement as HTMLElement">
          <Button>Adjust automatically</Button>
        </Tooltip>
        <Tooltip placement="left" title="Prompt Text" :get-popup-container="(t: HTMLElement) => t.parentElement as HTMLElement">
          <Button>Adjust automatically</Button>
        </Tooltip>
      </div>
    </div>
    <div ref="block2" :style="blockStyle">
      <div :style="innerStyle">
        <Tooltip placement="left" title="Prompt Text">
          <Button>Adjust automatically</Button>
        </Tooltip>
        <Tooltip placement="left" title="Prompt Text">
          <Button>Adjust automatically</Button>
        </Tooltip>
      </div>
    </div>
  </div>
</template>
```

## basic (basic)

最简单的用法。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/basic.tsx

import { Tooltip } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif">
    <Tooltip title="prompt text">
      <span>Tooltip will show on mouse enter.</span>
    </Tooltip>
  </div>
</template>
```

## colorful (colorful)

我们添加了多种预设色彩的文字提示样式，用作不同场景使用。

### colorful.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/colorful.tsx

import { Button, Divider, Space, Tooltip } from '@apollo-design/ui';

const colors = [
  'pink',
  'red',
  'yellow',
  'orange',
  'cyan',
  'green',
  'blue',
  'purple',
  'geekblue',
  'magenta',
  'volcano',
  'gold',
  'lime',
];
const customColors = ['#f50', '#2db7f5', '#87d068', '#108ee9'];
</script>

<template>
  <div style="font-family: sans-serif">
    <Divider title-placement="start">Presets</Divider>
    <Space wrap>
      <Tooltip v-for="color in colors" :key="color" title="prompt text" :color="color">
        <Button>{{ color }}</Button>
      </Tooltip>
    </Space>
    <Divider title-placement="start">Custom</Divider>
    <Space wrap>
      <Tooltip v-for="color in customColors" :key="color" title="prompt text" :color="color">
        <Button>{{ color }}</Button>
      </Tooltip>
    </Space>
  </div>
</template>
```

## debug (debug)

请开启开发者模式查看浮层的调试样式。

### debug.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/debug.tsx

import { Button, Flex, Tooltip } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif">
    <Flex vertical :gap="72" align="flex-start">
      <span />
      <Tooltip
        open
        title="Thanks for using antd. Have a nice day !"
        :arrow="{ pointAtCenter: true }"
        placement="topLeft"
      >
        <Button>Point at center</Button>
      </Tooltip>
      <Tooltip open placement="topLeft">
        <template #title><div /></template>
        <Button>Min Width</Button>
      </Tooltip>
      <Tooltip open placement="top">
        <template #title><div /></template>
        <Button>Min Width</Button>
      </Tooltip>
    </Flex>
  </div>
</template>
```

## destroy-on-close (destroy-on-close)

关闭后销毁浮层。

### destroy-on-close.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/destroy-on-close.tsx

import { Tooltip } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif">
    <Tooltip destroy-on-hidden title="prompt text">
      <span>Dom will destroyed when Tooltip close</span>
    </Tooltip>
  </div>
</template>
```

## disabled (disabled)

进行编辑操作时提示某些内容。

### disabled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/disabled.tsx

import { Button, Tooltip } from '@apollo-design/ui';
import { ref } from 'vue';

const disabled = ref(true);
</script>

<template>
  <div style="font-family: sans-serif">
    <!-- C8-R2：title 收窄 string；'' ⇒ noTitle 抑制（antd 的 null 语义等价） -->
    <Tooltip :title="disabled ? '' : 'prompt text'">
      <Button @click="disabled = !disabled">{{ disabled ? 'Enable' : 'Disable' }}</Button>
    </Tooltip>
  </div>
</template>
```

## disabled-children (disabled-children)

触发元素被禁用时，仍可显示提示。

### disabled-children.vue

```vue
<script setup lang="ts">
import { Checkbox, Input, InputNumber, Select, Space, Tooltip } from '@apollo-design/ui';
import { ref } from 'vue';

const checked = ref(true);
const text = ref('hello');
const num = ref(3);
const value = ref('aa');
</script>

<template>
  <Space wrap :size="12">
    <Tooltip title="prompt text">
      <Input v-model:value="text" placeholder="Input" :disabled="checked" style="width: 200px" />
    </Tooltip>
    <Tooltip title="prompt text">
      <InputNumber v-model:value="num" :disabled="checked" style="width: 120px" />
    </Tooltip>
    <Tooltip title="prompt text">
      <Select v-model:value="value" :disabled="checked" aria-label="demo select" :options="[{ value: 'aa', label: 'aa' }, { value: 'bb', label: 'bb' }]" style="width: 120px" />
    </Tooltip>
    <Checkbox v-model:checked="checked">Disabled</Checkbox>
  </Space>
</template>
```

## placement (placement)

位置有 12 个方向。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/placement.tsx

import { Button, Tooltip, type TooltipPlacement } from '@apollo-design/ui';

const rows: Array<Array<[TooltipPlacement, string]>> = [
  [
    ['topLeft', 'TL'],
    ['top', 'Top'],
    ['topRight', 'TR'],
  ],
  [
    ['leftTop', 'LT'],
    ['left', 'Left'],
    ['leftBottom', 'LB'],
  ],
  [
    ['rightTop', 'RT'],
    ['right', 'Right'],
    ['rightBottom', 'RB'],
  ],
  [
    ['bottomLeft', 'BL'],
    ['bottom', 'Bottom'],
    ['bottomRight', 'BR'],
  ],
];

const buttonWidth = 80;
</script>

<template>
  <div
    style="font-family: sans-serif; width: 480px; max-width: 100%; margin: 0 auto; display: flex; flex-direction: column; row-gap: 8px"
  >
    <template v-for="(row, i) in rows" :key="i">
      <div
        :style="{
          display: 'flex',
          justifyContent: i === 1 ? 'flex-start' : i === 2 ? 'flex-end' : 'center',
          gap: '4px',
          flexWrap: 'wrap',
          whiteSpace: 'nowrap',
        }"
      >
        <Tooltip v-for="[p, label] in row" :key="p" :title="p" :placement="p">
          <Button :style="{ width: buttonWidth + 'px', margin: '4px' }">{{ label }}</Button>
        </Tooltip>
      </div>
    </template>
  </div>
</template>
```

## render-panel (render-panel)

静态面板无需触发元素。切换、更新或清空原生 `#title`，验证空槽覆盖 prop，移除槽才恢复标题数据。原生字符串 style 与语义根样式按 Vue 规则合并。

### render-panel.vue

```vue
<script setup lang="ts">
import { Button, TooltipPurePanel } from '@apollo-design/ui';
import { ref } from 'vue';

const show = ref(false);
const empty = ref(false);
const count = ref(0);
</script>

<template>
  <div style="font-family: sans-serif">
    <p style="display: flex; flex-wrap: wrap; gap: 8px">
      <Button @click="show = !show">Toggle tooltip title</Button>
      <Button @click="empty = !empty">Empty tooltip title</Button>
      <Button @click="count++">Update tooltip title</Button>
    </p>
    <TooltipPurePanel title="Hello, Pink Pure Panel!" color="pink" />
    <TooltipPurePanel title="Hello, Customize Color Pure Panel!" color="#f50" />
    <TooltipPurePanel data-native-tooltip-panel title="Hello, Pure Panel!" placement="bottomLeft" style="width: 200px">
      <template v-if="show" #title><strong v-if="!empty">Native tooltip {{ count }}</strong></template>
    </TooltipPurePanel>
  </div>
</template>
```

## shift (shift)

超出滚动容器时自动移入视口（shift）。示例在独立视口内滚动，不会带动外层文档。

### shift.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/shift.tsx

import { Button, Tooltip } from '@apollo-design/ui';
import { onMounted } from 'vue';

onMounted(() => {
  window.scrollTo({
    top: document.documentElement.clientHeight,
    left: document.documentElement.clientWidth,
    behavior: 'instant',
  });
});

const style = {
  width: '300vw',
  height: '300vh',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center',
};
</script>

<template>
  <div :style="style">
    <Tooltip title="Thanks for using antd. Have a nice day !" open>
      <Button type="primary">Scroll The Window</Button>
    </Tooltip>
  </div>
</template>
```

## smooth-transition (smooth-transition)

平滑的过渡动画（shared popup 容器场景）。

### smooth-transition.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/smooth-transition.tsx（unique v1 不做 ⇒ 直接并排两个 Tooltip）

import { Button, Flex, Tooltip } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif">
    <Flex vertical gap="small">
      <Flex gap="small" justify="center">
        <Tooltip title="Hello, Ant Design!">
          <Button type="primary">Button</Button>
        </Tooltip>
        <Tooltip title="Hello, Ant Design!">
          <Button type="primary">Button</Button>
        </Tooltip>
      </Flex>
      <Flex gap="small" justify="center">
        <Tooltip title="Hello, Ant Design!" placement="bottom">
          <Button type="primary">Button</Button>
        </Tooltip>
        <Tooltip title="Hello, Ant Design!" placement="bottom">
          <Button type="primary">Button</Button>
        </Tooltip>
      </Flex>
    </Flex>
  </div>
</template>
```

## style-class (style-class)

语义化 `classNames` / `styles`（对象与函数两种形态），以及当前主题的 Tooltip maxWidth。第三个按钮可在提示打开时切换令牌。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/style-class.tsx（antd-style 的 createStaticStyles ⇒ 普通 object）

import { Button, ConfigProvider, Flex, Tooltip } from '@apollo-design/ui';
import { ref } from 'vue';

const maxWidth = ref(160);

const classNames = { container: 'demo-tooltip-container' };
const styles = { container: { borderRadius: '12px', boxShadow: 'inset 0 0 8px #ccc' } };
const stylesFn = (info: { props: { arrow?: unknown } }) => {
  if (!info.props.arrow) {
    return {
      container: {
        backgroundColor: 'rgba(53, 71, 125, 0.8)',
        padding: '12px',
        color: '#fff',
        borderRadius: '4px',
      },
    };
  }
  return {};
};
</script>

<template>
  <div style="font-family: sans-serif">
    <Flex wrap gap="medium">
      <Tooltip :class-names="classNames" :styles="styles" :arrow="false" title="Object text">
        <Button>Object Style</Button>
      </Tooltip>
      <Tooltip :class-names="classNames" :styles="stylesFn" :arrow="false" title="Function text">
        <Button type="primary">Function Style</Button>
      </Tooltip>
      <ConfigProvider :theme="{ components: { Tooltip: { maxWidth } } }">
        <Tooltip
          class="demo-current-tooltip"
          style="--demo-tooltip: current"
          title="Click to change the current Tooltip maxWidth token while this hint remains open."
        >
          <Button @click="maxWidth = maxWidth === 160 ? 280 : 160">Max width: {{ maxWidth }}px</Button>
        </Tooltip>
      </ConfigProvider>
    </Flex>
  </div>
</template>
```

## wrap-custom-component (wrap-custom-component)

包裹自定义组件（组件需要把事件与 ref 透传到根元素）。

### wrap-custom-component.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/wrap-custom-component.tsx

import { Tooltip } from '@apollo-design/ui';
</script>

<template>
  <div style="font-family: sans-serif">
    <Tooltip title="prompt text">
      <span>This text is inside a component with the necessary events exposed.</span>
    </Tooltip>
  </div>
</template>
```

---

# Tour

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/tour


# Tour 导览

用于分步引导用户了解页面功能。基于蒙层挖洞定位目标元素，支持键盘导航与自定义面板。

## 何时使用

- 当产品处于新功能上线或改版阶段，需要向用户分步介绍功能点时；
- 当希望用户按照指定顺序完成任务流程时；
- 当需要以「聚光灯」形式聚焦页面元素时。

## 引入

```ts
import { Tour } from '@apollo-design/ui';
```

## 代码演示



















## API

### TourProps

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| steps | 导览步骤配置 | TourStepProps[] | - |
| open | 是否打开（受控，`v-model:open`） | boolean | - |
| defaultOpen | 非受控初始打开态（不传 `open`/`defaultOpen` 且步骤合法时默认打开） | boolean | - |
| current | 当前步骤（受控，`v-model:current`） | number | 0 |
| defaultCurrent | 非受控初始步骤 | number | 0 |
| type | 面板形态 | 'default' \| 'primary' | 'default' |
| arrow | 是否显示箭头（被 `steps[].arrow` 覆盖） | boolean \| { pointAtCenter } | true |
| placement | 默认弹出位置（被 `steps[].placement` 覆盖；无 target 时兜底 `center`） | TourPlacement | 'bottom' |
| mask | 蒙层（被 `steps[].mask` 覆盖） | boolean \| { style?, color? } | true |
| gap | 高亮区相对目标的外扩 | { offset?: number \| [number, number]; radius?: number } | offset 6 / radius 2 |
| animated | 挖洞位动效 | boolean \| { placeholder } | true |
| keyboard | 键盘导航（Esc / ← / →） | boolean | true |
| closeIcon | 全局关闭图标（`#closeIcon` 插槽优先；被 `steps[].closeIcon` 覆盖） | VNodeChild | - |
| closable | 是否显示关闭按钮（被 `steps[].closable` 覆盖；对象上的 `aria-*` 透传到关闭按钮） | boolean \| { closeIcon?, ...aria } | - |
| scrollIntoViewOptions | 目标不在视口时的滚动选项 | boolean \| ScrollIntoViewOptions | { block: 'center', inline: 'center' } |
| zIndex | 浮层 z-index（不传走 `useZIndex` 层叠计算） | number | - |
| getPopupContainer | 挂载容器 | (node: HTMLElement) => HTMLElement \| ShadowRoot \| null | - |
| disabledInteraction | 蒙层是否拦截全部交互（含洞内） | boolean | false |
| builtinPlacements | 自定义 placement 配置表（默认由 `getPlacements` 生成） | Record&lt;string, AlignType&gt; | - |
| class | **根元素原生 attrs**（替代上游 `rootClassName`） | string / array / object | - |
| style / id / aria-* / 原生事件 | 唯一落到实际 popup 根；`style` 支持 Vue 对象、数组、字符串 | 原生 attrs | - |
| classNames / styles | 语义化槽位 ×12（对象或函数） | TourSemanticClassNames / TourSemanticStyles | - |

### TourStepProps

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| target | 高亮目标元素；getter 可返回尚未挂载的空 ref，`null` / `undefined` 表示居中显示 | HTMLElement \| (() => HTMLElement \| null \| undefined) \| null | - |
| title | 标题（`#title` 插槽优先） | string | - |
| description | 描述（`#description` 插槽优先） | string | - |
| cover | 封面（`#cover` 插槽优先，可传任意内容） | string | - |
| placement | 步骤级弹出位置 | TourPlacement | - |
| mask | 步骤级蒙层 | boolean \| { style?, color? } | - |
| arrow | 步骤级箭头 | boolean \| { pointAtCenter } | - |
| style | 步骤级面板样式（落到浮层根） | CSSProperties | - |
| className | 步骤级类名（拼在浮层根上） | string | - |
| scrollIntoViewOptions | 步骤级滚动选项 | boolean \| ScrollIntoViewOptions | - |
| closeIcon | 步骤级关闭图标 | VNodeChild | - |
| closable | 步骤级关闭配置 | boolean \| { closeIcon?, ...aria } | - |
| nextButtonProps | 下一步按钮（`children` 走 `#nextButton` 插槽优先；按钮类名用 Vue 原生 `class`） | { children?, onClick?, class?, style? } | - |
| prevButtonProps | 上一步按钮（`children` 走 `#prevButton` 插槽优先；按钮类名用 Vue 原生 `class`） | 同上 | - |
| type | 步骤级形态（覆盖 `TourProps.type`） | 'default' \| 'primary' | - |
| classNames / styles | 步骤级语义槽（不支持函数形态） | 同上 | - |

### 事件（Emits）

| 事件 | 说明 | 参数 |
| --- | --- | --- |
| update:open | `v-model:open` | (open: boolean) |
| update:current | `v-model:current` | (current: number) |
| change | 步骤变化（与 `update:current` 同时发出） | (current: number) |
| close | 关闭（Esc / 关闭按钮 / Finish），携带关闭时的 current | (current: number) |
| finish | 最后一步点「完成」 | - |
| popupAlign | 实际 popup 完成对齐后的通知 | (element: HTMLElement, align: TriggerAlign) |

### Slots

| 插槽 | 说明 | 参数 |
| --- | --- | --- |
| title / description / cover | 步骤内容（优先于同名 string prop） | { step, current, total } |
| closeIcon | 关闭图标（优先于 prop） | - |
| nextButton / prevButton | 按钮文案（优先于 `*.children`） | { step, current, total } |
| indicators | 自定义指示器（对应 `indicatorsRender`） | { current, total } |
| actions | 自定义操作区（对应 `actionsRender`；`originNode` 是可直接渲染的稳定默认操作组件） | { current, total, originNode } |

### TourPurePanel

`Tour._InternalPanelDoNotUseOrYouWillBeFired` 的对应物，静态面板（debug / 文档用）。仅接收标题、描述、封面、关闭配置、按钮配置和语义样式等渲染字段，另有 `prefixCls`、`current`（0）与 `total`（6）；支持同一套具名槽，不接收 `target`、`mask` 等定位参数。

### 主题变量

| Token | 说明 | 默认值 |
| --- | --- | --- |
| zIndexPopup | 浮层 z-index | zIndexPopupBase + 70（默认 1070） |
| closeBtnSize | 关闭按钮尺寸 | fontSize × lineHeight = 22px |
| primaryPrevBtnBg | primary 形态「上一步」背景 | rgba(255,255,255,0.15) |
| primaryNextBtnHoverBg | primary 形态「下一步」hover 背景 | rgb(240,240,240) |

箭头族（arrowOffsetHorizontal / arrowOffsetVertical / arrowShadowWidth / arrowPath / arrowPolygon）与 tooltip / dropdown 同源，不重复声明。

## 状态、焦点与更新

`open` 与 `current` 各只有一个控制来源。受控操作只提出更新；父级拒绝时保持当前显示和焦点，撤控从最后接受值继续。步骤数组暂时为空或当前下标越界时隐藏，恢复合法步骤后保留接受的下标。真正重新打开时，仅非受控 `current` 静默归零，不发送 `change`。

方向键在导览面板内生效，并尊重输入控件、IME 与原生事件取消；Esc 只由最上层导览处理。打开时聚焦实际面板，不锁住允许交互的目标洞；接受关闭后恢复所属焦点，用户已移到外部时不抢回。`mask=false` 不锁滚动、不截获页面交互。

目标、祖先尺寸变化与捕获阶段滚动继续通过既有 s53 合帧链更新几何；关闭、切换目标与卸载会注销观察与监听并取消待执行帧。仅打开或更换目标/滚动选项时请求 `scrollIntoView`，不在被动滚动中反复拉回目标。父尺寸不变的纯位置重排仍不额外引入 DOM 观察或轮询。

具名槽在渲染期读取；存在但为空的槽不退回数据文本。`actions` 中使用 `<component :is="originNode" />`，组件身份在步骤和主题更新中保持稳定。每步 `nextButtonProps.onClick` / `prevButtonProps.onClick` 是数据动作，接收真实 `MouseEvent`，可 `preventDefault()` 取消默认步骤流转。

Provider、语言和现有 Token 在普通面板与 PurePanel 中读取当前值；优先级为 Provider → 顶层语义配置 → 当前步骤 → 原生根 attrs。显式 `styles.root` 的遮罩投影保留，原生 `class/style` 只作用 popup。顶层使用当前 Tour Token 层级，嵌套沿现有父层偏移，显式 `zIndex=0` 有效。

### 迁移

`onPopupAlign` 改为 Vue `popupAlign` 事件；模板用 `@popup-align`，`h()` 的 `onPopupAlign` 仍是监听器。`actions.originNode` 改为稳定组件，删除 `() => originNode` / VNode 类型断言，直接交给 `:is`。原生 attrs 从不可见 placeholder 迁到实际 popup；通过 `styles.mask` 单独控制遮罩。Tour 没有公开实例控制 API。


## 基本 (basic)

最简单的用法。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/basic.tsx
// cover 是 VNode ⇒ 走 #cover 插槽（C8-R2；prop 已收窄为 string）
import { EllipsisOutlined } from '@apollo-design/icons';
import { Button, Divider, Space, Tour } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);

const ref1 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref2 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref3 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);

const target1 = () => ref1.value?.nativeElement;
const target2 = () => ref2.value?.nativeElement;
const target3 = () => ref3.value?.nativeElement;

const steps = [
  {
    title: 'Upload File',
    description: 'Put your files here.',
    target: target1,
  },
  {
    title: 'Save',
    description: 'Save your changes.',
    target: target2,
  },
  {
    title: 'Other Actions',
    description: 'Click to see other actions.',
    target: target3,
  },
];
</script>

<template>
  <Button type="primary" @click="open = true">Begin Tour</Button>
  <Divider />
  <Space wrap>
    <Button ref="ref1">Upload</Button>
    <Button ref="ref2" type="primary">Save</Button>
    <Button ref="ref3" :icon="EllipsisOutlined" />
  </Space>
  <Tour :open="open" :steps="steps" @close="open = false">
    <template #cover="{ current }">
      <img
        v-if="current === 0"
        draggable="false"
        alt="tour.png"
        src="https://user-images.githubusercontent.com/5378891/197385811-55df8480-7ff4-44bd-9d43-a7dade598d70.png"
      />
    </template>
  </Tour>
</template>
```

## 自定义蒙层 (mask)

自定义蒙层样式。

### mask.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/mask.tsx：默认蒙层 / 对象形态（style + color）/ 关闭蒙层
import { EllipsisOutlined } from '@apollo-design/icons';
import { Button, Divider, Space, Tour } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);

const ref1 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref2 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref3 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);

const target1 = () => ref1.value?.nativeElement;
const target2 = () => ref2.value?.nativeElement;
const target3 = () => ref3.value?.nativeElement;

const steps = [
  {
    title: 'Upload File',
    description: 'Put your files here.',
    target: target1,
  },
  {
    title: 'Save',
    description: 'Save your changes.',
    target: target2,
    mask: {
      style: {
        boxShadow: 'inset 0 0 15px #fff',
      },
      color: 'rgba(40, 0, 255, .4)',
    },
  },
  {
    title: 'Other Actions',
    description: 'Click to see other actions.',
    target: target3,
    mask: false,
  },
];
</script>

<template>
  <Button type="primary" @click="open = true">Begin Tour</Button>
  <Divider />
  <Space wrap>
    <Button ref="ref1">Upload</Button>
    <Button ref="ref2" type="primary">Save</Button>
    <Button ref="ref3" :icon="EllipsisOutlined" />
  </Space>
  <Tour :open="open" :steps="steps" @close="open = false">
    <template #cover="{ current }">
      <img
        v-if="current === 0"
        draggable="false"
        alt="tour.png"
        src="https://user-images.githubusercontent.com/5378891/197385811-55df8480-7ff4-44bd-9d43-a7dade598d70.png"
      />
    </template>
  </Tour>
</template>
```

## 非模态 (non-modal)

使用 `mask=false` 可以将引导变为非模态，同时为了强调引导本身，建议与 `type="primary"` 组合使用。

### non-modal.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/non-modal.tsx：mask=false + type="primary"
import { EllipsisOutlined } from '@apollo-design/icons';
import { Button, Divider, Space, Tour } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);

const ref1 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref2 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref3 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);

const target1 = () => ref1.value?.nativeElement;
const target2 = () => ref2.value?.nativeElement;
const target3 = () => ref3.value?.nativeElement;

const steps = [
  {
    title: 'Upload File',
    description: 'Put your files here.',
    target: target1,
  },
  {
    title: 'Save',
    description: 'Save your changes.',
    target: target2,
  },
  {
    title: 'Other Actions',
    description: 'Click to see other actions.',
    target: target3,
  },
];
</script>

<template>
  <Button type="primary" @click="open = true">Begin non-modal Tour</Button>
  <Divider />
  <Space wrap>
    <Button ref="ref1">Upload</Button>
    <Button ref="ref2" type="primary">Save</Button>
    <Button ref="ref3" :icon="EllipsisOutlined" />
  </Space>
  <Tour :open="open" :mask="false" type="primary" :steps="steps" @close="open = false">
    <template #cover="{ current }">
      <img
        v-if="current === 0"
        draggable="false"
        alt="tour.png"
        src="https://user-images.githubusercontent.com/5378891/197385811-55df8480-7ff4-44bd-9d43-a7dade598d70.png"
      />
    </template>
  </Tour>
</template>
```

## 自定义操作区 (actions-render)

通过 `#actions` 插槽（对应 `actionsRender`）自定义操作区，`originNode` 是默认的「上一步 / 下一步」按钮组。

### actions-render.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/actions-render.tsx：#actions scoped slot（originNode + Skip 按钮）
import { Button, Divider, Space, Tour } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);

const ref1 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref2 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref3 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);

const target1 = () => ref1.value?.nativeElement;
const target2 = () => ref2.value?.nativeElement;
const target3 = () => ref3.value?.nativeElement;

const steps = [
  { title: 'Upload File', description: 'Put your files here.', target: target1 },
  { title: 'Save', description: 'Save your changes.', target: target2 },
  { title: 'Other Actions', description: 'Click to see other actions.', target: target3 },
];
</script>

<template>
  <Button type="primary" @click="open = true">Begin Tour</Button>
  <Divider />
  <Space wrap>
    <Button ref="ref1">Upload</Button>
    <Button ref="ref2" type="primary">Save</Button>
    <Button ref="ref3">...</Button>
  </Space>
  <Tour :open="open" :steps="steps" @close="open = false">
    <template #actions="{ current, total, originNode }">
      <template v-if="current !== total - 1">
        <Button size="small" @click="open = false">Skip</Button>
      </template>
      <template v-if="originNode !== undefined">
        <component :is="originNode" />
      </template>
    </template>
  </Tour>
</template>
```

## 自定义指示器 (indicator)

通过 `#indicators` 插槽（对应 `indicatorsRender`）自定义指示器。

### indicator.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/indicator.tsx：#indicators scoped slot
import { Button, Divider, Space, Tour } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);

const ref1 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref2 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref3 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);

const target1 = () => ref1.value?.nativeElement;
const target2 = () => ref2.value?.nativeElement;
const target3 = () => ref3.value?.nativeElement;

const steps = [
  { title: 'Upload File', description: 'Put your files here.', target: target1 },
  { title: 'Save', description: 'Save your changes.', target: target2 },
  { title: 'Other Actions', description: 'Click to see other actions.', target: target3 },
];
</script>

<template>
  <Button type="primary" @click="open = true">Begin Tour</Button>
  <Divider />
  <Space wrap>
    <Button ref="ref1">Upload</Button>
    <Button ref="ref2" type="primary">Save</Button>
    <Button ref="ref3">...</Button>
  </Space>
  <Tour :open="open" :steps="steps" @close="open = false">
    <template #indicators="{ current, total }">
      <span>{{ current + 1 }} / {{ total }}</span>
    </template>
  </Tour>
</template>
```

## 位置 (placement)

第一个步骤没有 `target`，引导面板会居中显示；其余步骤用 `placement` 指定弹出位置。

### placement.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/placement.tsx：center（无 target 兜底）/ right / top
import { Button, Tour } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const ref1 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);

const target = () => ref1.value?.nativeElement;

import type { TourStepProps } from '../interface';

const steps: TourStepProps[] = [
  {
    title: 'Center',
    description: 'Displayed in the center of screen.',
    target: null,
  },
  {
    title: 'Right',
    description: 'On the right of target.',
    placement: 'right',
    target,
  },
  {
    title: 'Top',
    description: 'On the top of target.',
    placement: 'top',
    target,
  },
];
</script>

<template>
  <Button ref="ref1" type="primary" @click="open = true">Begin Tour</Button>
  <Tour :open="open" :steps="steps" @close="open = false" />
</template>
```

### ../interface.ts

```ts
/** Native Tour contracts. Historical source references do not override the current Vue API. */

import type { TourLocale } from '@apollo-design/locale';
import type { ClassValue, Component, CSSProperties, VNodeChild } from 'vue';

import type { TriggerAlign } from '../_internal/trigger';

// ---------------------------------------------------------------------------
// placement / gap（rc-tour 的两个自有类型）
// ---------------------------------------------------------------------------

/**
 * rc `placements.ts` 的 `PlacementType` —— 13 个值（含 `center`）。
 *
 * ⚠️ 与 `@apollo-design/position` 的 12 个 placement 的差别是多了 `'center'`
 *    （rc-tour 专有：无目标时居中）。本仓的 `getPlacements` 只覆盖 12 个，
 *    `'center'` 需在 G4 单独补一个 align 配置。
 */
export type TourPlacement =
  | 'left'
  | 'leftTop'
  | 'leftBottom'
  | 'right'
  | 'rightTop'
  | 'rightBottom'
  | 'top'
  | 'topLeft'
  | 'topRight'
  | 'bottom'
  | 'bottomLeft'
  | 'bottomRight'
  | 'center';

/**
 * rc `hooks/useTarget.ts` 的 `Gap` —— 高亮区相对目标元素的外扩。
 *
 * `offset` 为单值时四边等量外扩；二元组是 `[水平, 垂直]`。`radius` 是高亮区圆角。
 */
export interface TourGap {
  offset?: number | [number, number];
  radius?: number;
}

/** `mask` 的对象形态（`boolean` 之外）。 */
export interface TourMaskConfig {
  style?: CSSProperties;
  color?: string;
}

/** `arrow` 的对象形态（`boolean` 之外）。 */
export interface TourArrowConfig {
  pointAtCenter: boolean;
}

/** `animated` 的对象形态（`boolean` 之外）。 */
export interface TourAnimatedConfig {
  placeholder: boolean;
}

/** `closable` 的对象形态（`false` 之外）—— 其上的 `aria-*` / `data-*` 透传到关闭按钮。 */
export interface TourClosableConfig {
  closeIcon?: VNodeChild;
  /** `aria-*` 透传（antd 用 `pickAttrs(closable, true)` 取）。 */
  [key: `aria-${string}`]: unknown;
  /** `data-*` 透传。 */
  [key: `data-${string}`]: unknown;
}

/** `'default'`（白底）/ `'primary'`（主色底）。 */
export type TourType = 'default' | 'primary';

// ---------------------------------------------------------------------------
// 语义化槽位（12 个）
// ---------------------------------------------------------------------------

/** 语义化类名的 12 个槽位。与 antd `TourSemanticType['classNames']` 一致。 */
export interface TourSemanticClassNames {
  root?: string;
  cover?: string;
  close?: string;
  mask?: string;
  section?: string;
  footer?: string;
  actions?: string;
  indicator?: string;
  indicators?: string;
  header?: string;
  title?: string;
  description?: string;
}

/** 语义化样式的 12 个槽位。 */
export interface TourSemanticStyles {
  root?: CSSProperties;
  cover?: CSSProperties;
  close?: CSSProperties;
  mask?: CSSProperties;
  section?: CSSProperties;
  footer?: CSSProperties;
  actions?: CSSProperties;
  indicator?: CSSProperties;
  indicators?: CSSProperties;
  header?: CSSProperties;
  title?: CSSProperties;
  description?: CSSProperties;
}

/**
 * 语义化输入：对象或函数。
 *
 * 对应 antd `GenerateSemantic<TourSemanticType, TourProps>` 的
 * `classNamesAndFn` / `stylesAndFn`（裁决 `empty-semantic-fn` = B 支持函数形态）。
 */
export type TourSemanticValue<T> = T | ((info: { props: TourProps }) => T);

/** antd 的 `TourSemanticType`（不含函数式的形态）。 */
export interface TourSemanticType {
  classNames?: TourSemanticClassNames;
  styles?: TourSemanticStyles;
}

/** antd 的 `TourSemanticAllType`（含函数式的完整形态）。 */
export interface TourSemanticAllType {
  classNames: TourSemanticClassNames;
  classNamesAndFn: TourSemanticValue<TourSemanticClassNames>;
  styles: TourSemanticStyles;
  stylesAndFn: TourSemanticValue<TourSemanticStyles>;
}

// ---------------------------------------------------------------------------
// 步骤
// ---------------------------------------------------------------------------

/** 步骤上的按钮配置（`nextButtonProps` / `prevButtonProps`）；按钮根样式使用 Vue 原生 attrs。 */
export interface TourButtonProps {
  /** slot `#nextButton` / `#prevButton` 优先；此 prop 为字符串兜底。 */
  children?: string;
  onClick?: (event: MouseEvent) => void;
  /** Vue 原生 class attrs，落在步骤操作按钮上。 */
  class?: ClassValue;
  style?: CSSProperties;
}

/**
 * 单个步骤（antd `TourStepProps` = rc `TourStepInfo` + 面板注入 + antd 追加）。
 *
 * ⚠️ `prefixCls` / `total` / `current` / `onClose` / `onFinish` / `onPrev` / `onNext` /
 *    `renderPanel` 是 **rc/antd 的面板注入位**，不是用户的公开面 —— 本仓不暴露
 *    （`renderPanel` 上游也已 `Omit`）。用户面只有下面这些 + `TourProps` 上的兜底值。
 */
export interface TourStepProps {
  /**
   * 高亮的目标元素。`null` 表示**无目标**（居中显示）。
   * ⚠️ React 的 `() => HTMLElement` 在 Vue 里保留函数形态（与 ref 取值时机有关）。
   */
  target?: HTMLElement | (() => HTMLElement | null | undefined) | null;
  /** 标题。slot `#title` 优先。 */
  title?: string;
  /** 描述。slot `#description` 优先。 */
  description?: string;
  /** 封面图。slot `#cover` 优先。 */
  cover?: string;
  /** 单个步骤的 placement；不传则用 `TourProps.placement`。 */
  placement?: TourPlacement;
  /** 单个步骤的蒙层；不传则用 `TourProps.mask`。 */
  mask?: boolean | TourMaskConfig;
  /** 单个步骤的箭头；不传则用 `TourProps.arrow`。 */
  arrow?: boolean | TourArrowConfig;
  /** 单个步骤的类名（antd 会额外拼 `-primary`，见 `TourProps.type`）。 */
  className?: string;
  /** 单个步骤的行内样式。 */
  style?: CSSProperties;
  /** 滚动进视野的选项；`false` 关闭。 */
  scrollIntoViewOptions?: boolean | ScrollIntoViewOptions;
  /** 单个步骤的关闭图标（覆盖 `TourProps.closeIcon`）。 */
  closeIcon?: VNodeChild;
  /** `false` 不显示关闭按钮；对象形态可带 `closeIcon` 与 `aria-*` / `data-*`。 */
  closable?: boolean | TourClosableConfig;
  /** 单个步骤的 `type`；**覆盖** `TourProps.type`（`mergedType = stepType ?? type`）。 */
  type?: TourType;
  nextButtonProps?: TourButtonProps;
  prevButtonProps?: TourButtonProps;
  /** 步骤级语义化槽位（**不支持**函数形态，同 antd）。 */
  classNames?: TourSemanticClassNames;
  /** 步骤级语义化样式（**不支持**函数形态，同 antd）。 */
  styles?: TourSemanticStyles;
}

// ---------------------------------------------------------------------------
// Props
// ---------------------------------------------------------------------------

export interface TourProps {
  'onUpdate:open'?: (open: boolean) => void;
  'onUpdate:current'?: (current: number) => void;
  onChange?: (current: number) => void;
  onClose?: (current: number) => void;
  onFinish?: () => void;
  /** 类名前缀。不传则从 ConfigProvider 取，兜底 `apollo`。 */
  prefixCls?: string;
  /** 是否打开（受控）。配合 `v-model:open` 使用。 */
  open?: boolean;
  /** 非受控初始打开态。 */
  defaultOpen?: boolean;
  /** 当前步骤（受控，从 0 起）。配合 `v-model:current` 使用。 */
  current?: number;
  /** 非受控初始步骤。 */
  defaultCurrent?: number;
  /** 步骤列表。 */
  steps?: TourStepProps[];
  /** 全局形态；被 `steps[].type` 覆盖。 */
  type?: TourType;
  /**
   * 键盘：`Esc` 关闭、`←/→` 切换步骤。
   * @default true
   */
  keyboard?: boolean;
  /** 全局蒙层；被 `steps[].mask` 覆盖。 */
  mask?: boolean | TourMaskConfig;
  /** 全局箭头；被 `steps[].arrow` 覆盖。 */
  arrow?: boolean | TourArrowConfig;
  /** 全局 placement；被 `steps[].placement` 覆盖。 */
  placement?: TourPlacement;
  /** 高亮区相对目标的外扩。 */
  gap?: TourGap;
  /** 入场/离场动效。antd 恒传 `true`；对象形态控制 placeholder 的动效。 */
  animated?: boolean | TourAnimatedConfig;
  /** 全局滚动选项；被 `steps[].scrollIntoViewOptions` 覆盖。 */
  scrollIntoViewOptions?: boolean | ScrollIntoViewOptions;
  /** 全局关闭图标（slot `#closeIcon` 优先）。 */
  closeIcon?: VNodeChild;
  /** 全局 `closable`；被 `steps[].closable` 覆盖。 */
  closable?: boolean | TourClosableConfig;
  /** 浮层 z-index。不传由 `useZIndex('Tour')` 计算。 */
  zIndex?: number;
  /** 挂载容器。 */
  getPopupContainer?: (node: HTMLElement) => HTMLElement | ShadowRoot | null;
  /** 自定义 placement 配置表（默认由 `getPlacements` 生成）。 */
  builtinPlacements?: Record<string, TriggerAlign>;
  /** 蒙层是否拦截交互（`true` 时蒙层可点，不穿透）。 */
  disabledInteraction?: boolean;
  /** Vue popupAlign 事件监听器；不作为回调 prop 调用。 */
  onPopupAlign?: (element: HTMLElement, align: TriggerAlign) => void;
  /** 语义化类名（对象或函数）。 */
  classNames?: TourSemanticValue<TourSemanticClassNames>;
  /** 语义化样式（对象或函数）。 */
  styles?: TourSemanticValue<TourSemanticStyles>;
}

// ---------------------------------------------------------------------------
// Emits / Slots
// ---------------------------------------------------------------------------

/** 事件面。`v-model:open` / `v-model:current` 与语义事件**同时**发出（规则 C11）。 */
export interface TourEmits {
  /** `v-model:open` —— 打开态变化。 */
  (e: 'update:open', open: boolean): void;
  /** `v-model:current` —— 当前步骤变化。 */
  (e: 'update:current', current: number): void;
  /** 步骤变化（与 `update:current` 同时发出）。 */
  (e: 'change', current: number): void;
  /** 关闭（含 `Esc` / 关闭按钮 / 完成），携带关闭时的步骤下标。 */
  (e: 'close', current: number): void;
  /** 最后一步点「完成」。 */
  (e: 'finish'): void;
  (e: 'popupAlign', element: HTMLElement, align: TriggerAlign): void;
}

/**
 * 插槽面（规则 C8-R2：VNode 一律走 slot）。
 *
 * `title` / `description` / `cover` / `nextButton` / `prevButton` 的 slot **优先于**
 * 同名 `string` prop。`indicators` / `actions` 是 antd 两个 render prop 的 scoped slot。
 */
export type TourSlots = {
  /** 标题（优先于 `steps[].title`）。 */
  title?: (props: { step: TourStepProps; current: number; total: number }) => VNodeChild;
  /** 描述（优先于 `steps[].description`）。 */
  description?: (props: { step: TourStepProps; current: number; total: number }) => VNodeChild;
  /** 封面（优先于 `steps[].cover`）。 */
  cover?: (props: { step: TourStepProps; current: number; total: number }) => VNodeChild;
  /** 关闭图标（优先于 `closeIcon` prop）。 */
  closeIcon?: () => VNodeChild;
  /** 下一步按钮内容（优先于 `nextButtonProps.children`）。 */
  nextButton?: (props: { step: TourStepProps; current: number; total: number }) => VNodeChild;
  /** 上一步按钮内容（优先于 `prevButtonProps.children`）。 */
  prevButton?: (props: { step: TourStepProps; current: number; total: number }) => VNodeChild;
  /** 自定义指示器（对应 antd `indicatorsRender`）。 */
  indicators?: (props: { current: number; total: number }) => VNodeChild;
  /**
   * 自定义操作区（对应 antd `actionsRender`）。
   * `originNode` 是可直接渲染且身份稳定的默认操作组件。
   */
  actions?: (props: { current: number; total: number; originNode: Component }) => VNodeChild;
};

// ---------------------------------------------------------------------------
// PurePanel / locale 再导出
// ---------------------------------------------------------------------------

/** `_InternalPanelDoNotUseOrYouWillBeFired` 的 props（= `TourStepProps`）。 */
export type TourPurePanelProps = Pick<
  TourStepProps,
  | 'title'
  | 'description'
  | 'cover'
  | 'type'
  | 'closable'
  | 'closeIcon'
  | 'classNames'
  | 'styles'
  | 'nextButtonProps'
  | 'prevButtonProps'
> & { prefixCls?: string; current?: number; total?: number };

export type { TourLocale };
```

### ../../_internal/trigger.ts

```ts
/**
 * `Trigger` —— `@rc-component/trigger@3.10.1` 的 Vue 等价物（tooltip 的第一消费者，
 * dropdown / select / cascader / date-picker 等后续复用）。
 *
 * ── 组装关系（tooltip 的实现 = 组装，见 docs/analysis/tooltip.md §1/§8） ──────
 *
 * | rc 侧 | 本仓承接 |
 * |---|---|
 * | `hooks/useAction` + `useDelay` + `useWinClick` + portal 的 Esc 栈 | `@apollo-design/overlay` 的 `useOverlay()` |
 * | `hooks/useAlign`（几何） | `@apollo-design/position` 的 `measureAlign()` + `alignPopup()`（+ 本文件补齐 offsetR/B） |
 * | `@rc-component/portal` | `@apollo-design/portal` 的 `Portal` |
 * | `@rc-component/motion` 的 CSSMotion | `@apollo-design/motion` 的 `CSSMotion` |
 *
 * ── 与 rc 的已知差异（全部登记过，不要当 bug 修） ─────────────────────────
 *
 * 1. **事件顺序**：rc 的 wrapperAction 是「先 `triggerOpen`，后用户自己的同名
 *    handler」；Vue 的 `cloneVNode` 把事件合并成 `[child 自己的, 我们注入的]`
 *    （`mergeProps` 对后来的追加在后，而 cloneVNode 先 merge(child.props, extra)）
 *    ⇒ 用户 handler 先跑。延迟/开关语义不受影响（PLATFORM，D 候选）。
 * 2. **offsetR/B 的亚像素差**：rc 用未 floor 的原始 offsetX 参与 offsetR/B
 *    计算；`alignPopup` 返回的是已 floor 的值。scale=1（常态）时两边一致，
 *    scale≠1 时差 <1px（analysis §8）。
 * 3. **unique / mask / mobile / stretch** 不做（v1 范围；UniqueProvider 是
 *    性能优化，语义等价）。
 * 4. **回调通道**：内部组件走**纯 prop 回调**（`onOpenChange` 等），不声明
 *    emits —— prop 与 emit 同名会双触发（CHECKLIST #78）。
 *
 * ⚠️ `targetProps` / `popupProps` 的事件键是 **Vue 小写约定**（`onMouseenter`，
 *    overlay-contract §6.1）—— useOverlay 已经按此产出，这里别再改写。
 */

import { CSSMotion } from '@apollo-design/motion';
import { type OverlayActionInput, useOverlay } from '@apollo-design/overlay';
import { Portal } from '@apollo-design/portal';
import {
  type AlignOutcome,
  type AlignType,
  alignPopup,
  collectScroller,
  type FlipMemory,
  measureAlign,
} from '@apollo-design/position';
import { transformToken, useTheme } from '@apollo-design/theme';
import { canUseDom, getElement, isHTMLElement } from '@apollo-design/utils';
import {
  type CSSProperties,
  cloneVNode,
  computed,
  defineComponent,
  h,
  mergeProps,
  nextTick,
  type PropType,
  ref,
  shallowRef,
  type VNode,
  type VNodeChild,
  watch,
} from 'vue';

// ---------------------------------------------------------------------------
// 类型
// ---------------------------------------------------------------------------

export type TriggerAlign = AlignType;

export interface TriggerMotion {
  motionName?: string;
  motionDeadline?: number;
  /** 透传 CSSMotion 的 supportMotion（测试里必须显式传 true，jsdom 探测不可靠） */
  supportMotion?: boolean;
}

export interface TriggerArrow {
  className?: string;
  style?: CSSProperties;
  content?: VNodeChild;
}

/**
 * 目标矩形是否完全落在可视区外。
 *
 * 纯函数以便单测穷举：jsdom 无布局时矩形恒为 0，真实分支只能靠这里钉住。
 * 零尺寸矩形返回 `false`（无法判定 ⇒ 仍然对齐，保持既有 jsdom 行为）。
 */
export function isTargetOutsideArea(
  rect: { left: number; top: number; right: number; bottom: number; width: number; height: number },
  area: { left: number; top: number; right: number; bottom: number },
): boolean {
  if (rect.width <= 0 || rect.height <= 0) return false;
  return (
    rect.right <= area.left ||
    rect.left >= area.right ||
    rect.bottom <= area.top ||
    rect.top >= area.bottom
  );
}

/** rc `useAlign` 的 offsetInfo。 */
interface OffsetInfo {
  ready: boolean;
  offsetX: number;
  offsetY: number;
  offsetR: number;
  offsetB: number;
  arrowX: number;
  arrowY: number;
  scaleX: number;
  scaleY: number;
  align: TriggerAlign;
}

// ---------------------------------------------------------------------------
// rc `util.js` 的 getAlignPopupClassName（机械移植）
// ---------------------------------------------------------------------------

function isPointsEq(
  a1: readonly string[] = [],
  a2: readonly string[] = [],
  isAlignPoint: boolean,
): boolean {
  const getVal = (a: readonly string[], index: number) => a[index] || '';
  if (isAlignPoint) {
    return getVal(a1, 0) === getVal(a2, 0);
  }
  return getVal(a1, 0) === getVal(a2, 0) && getVal(a1, 1) === getVal(a2, 1);
}

export function getAlignPopupClassName(
  builtinPlacements: Record<string, TriggerAlign>,
  prefixCls: string,
  align: TriggerAlign | undefined,
  isAlignPoint: boolean,
): string {
  const points = align?.points;
  for (const placement of Object.keys(builtinPlacements)) {
    if (isPointsEq(builtinPlacements[placement]?.points, points, isAlignPoint)) {
      return `${prefixCls}-placement-${placement}`;
    }
  }
  return '';
}

// ---------------------------------------------------------------------------
// 触发元素归一（Vue 的 ref 在组件 vnode 上给的是**实例**，契约要的是元素）
// ---------------------------------------------------------------------------

/**
 * 把 Vue 的 ref 回调值归一成 DOM 元素：`null` / 元素 / 组件实例（读 `$el`）。
 *
 * ⚠️ 组件实例的 `$el` 未必是元素（多根组件是文本节点 / Fragment 占位注释）
 * ⇒ 取不到就回落 `null`，与「未绑 ref」同判（rc 的可选链语义）。
 */
function resolveTriggerElement(value: unknown): HTMLElement | null {
  const element = getElement(value);
  return isHTMLElement(element) ? element : null;
}

// ---------------------------------------------------------------------------
// 组件
// ---------------------------------------------------------------------------

export const Trigger = defineComponent({
  name: 'ATrigger',
  inheritAttrs: false,
  props: {
    prefixCls: { type: String, required: true },
    /** 浮层内容（rc 的 `popup`；函数形态每次渲染求值）。 */
    popup: {
      type: [Object, String, Number, Function] as PropType<VNodeChild | (() => VNodeChild)>,
      default: undefined,
    },
    action: { type: [String, Array] as PropType<OverlayActionInput>, default: undefined },
    showAction: { type: [String, Array] as PropType<OverlayActionInput>, default: undefined },
    hideAction: { type: [String, Array] as PropType<OverlayActionInput>, default: undefined },
    /** 受控开合。传了即受控（tooltip 恒受控 —— noTitle 抑制在外层做）。 */
    open: { type: Boolean, default: undefined },
    defaultOpen: { type: Boolean, default: undefined },
    onOpenChange: { type: Function as PropType<(open: boolean) => void>, default: undefined },
    afterOpenChange: { type: Function as PropType<(open: boolean) => void>, default: undefined },
    disabled: { type: Boolean, default: undefined },
    /** 单位**秒**。 */
    mouseEnterDelay: { type: Number, default: undefined },
    mouseLeaveDelay: { type: Number, default: undefined },
    focusDelay: { type: Number, default: undefined },
    blurDelay: { type: Number, default: undefined },
    /** 按鼠标位置定位（右键菜单场景）。 */
    alignPoint: { type: Boolean, default: undefined },
    placement: { type: String, default: 'top' },
    /** `getPlacements()` 的产物。 */
    builtinPlacements: { type: Object as PropType<Record<string, TriggerAlign>>, required: true },
    /** 用户 align 浅合并到对应 placement 之上（rc 的 `popupAlign`）。 */
    popupAlign: { type: Object as PropType<TriggerAlign>, default: undefined },
    getPopupContainer: {
      type: Function as PropType<(triggerNode: HTMLElement) => HTMLElement | ShadowRoot | null>,
      default: undefined,
    },
    motion: { type: Object as PropType<TriggerMotion>, default: undefined },
    /** 关闭且动画结束后卸载 portal（rc 的 `autoDestroy`）。 */
    destroyOnHidden: { type: Boolean, default: undefined },
    /** 关闭后仍挂载 portal。 */
    forceRender: { type: Boolean, default: undefined },
    /** 关闭时不缓存内容（rc 的 `fresh`）。 */
    fresh: { type: Boolean, default: undefined },
    /**
     * 拉伸协议（rc 的 `stretch`）：'minWidth' ⇒ 浮层 min-width = 目标宽度
     * （dropdown 的 minOverlayWidthMatchTrigger 默认真）。对齐时量测并写入。
     */
    stretch: { type: String as PropType<'minWidth'>, default: undefined },
    /** 箭头。`undefined` 视为无箭头（rc-tooltip 先算好 mergedArrow 再传入）。 */
    arrow: { type: Object as PropType<TriggerArrow>, default: undefined },
    zIndex: { type: Number, default: undefined },
    popupClassName: { type: [String, Array] as PropType<string | string[]>, default: undefined },
    popupStyle: { type: Object as PropType<CSSProperties>, default: undefined },
    /** Native attrs for consumers whose trigger is a positioning placeholder. */
    popupAttrs: { type: Object as PropType<Record<string, unknown>>, default: undefined },
    onPopupAlign: {
      type: Function as PropType<(popupEle: HTMLElement, align: TriggerAlign) => void>,
      default: undefined,
    },
  },
  setup(props, { slots, attrs, expose }) {
    const theme = useTheme();
    // Native Portal keeps injection, but leaves the Provider's DOM/CSS scope.
    // Apply the current source aliases to the popup itself; local popup styles still win.
    const popupThemeStyle = computed(() =>
      theme.sourceActive?.value !== false ? transformToken(theme.token.value).vars : undefined,
    );
    // ============================ Overlay ============================
    // 开合 / 事件 / 延迟 / Esc / 外部点击 —— 全部委托 overlay。
    const inMotion = ref(false);
    const overlay = useOverlay({
      action: () => props.action,
      showAction: () => props.showAction,
      hideAction: () => props.hideAction,
      open: () => props.open,
      defaultOpen: props.defaultOpen,
      onOpenChange: (next) => props.onOpenChange?.(next),
      disabled: () => props.disabled,
      mouseEnterDelay: () => props.mouseEnterDelay,
      mouseLeaveDelay: () => props.mouseLeaveDelay,
      focusDelay: () => props.focusDelay,
      blurDelay: () => props.blurDelay,
      alignPoint: () => props.alignPoint,
      inMotion: () => inMotion.value,
    });
    const mergedOpen = overlay.open;

    // ============================ Motion ============================
    // rc：useLayoutEffect(firstMount => { if (!firstMount || mergedOpen) setInMotion(true) },
    // [mergedOpen]) —— 首挂且 open=true 也置位；onVisibleChanged 清零。
    watch(mergedOpen, () => {
      inMotion.value = true;
    });
    if (canUseDom() && mergedOpen.value) {
      inMotion.value = true;
    }

    // ============================ Align =============================
    const popupEle = shallowRef<HTMLElement | null>(null);
    /**
     * ⭐ 浮层元素的**唯一**写入口。
     *
     * `overlay.popupRef` 不是可选的装饰 —— 它是 `@apollo-design/overlay` 契约的一部分，
     * 两处行为依赖它（缺了就是「接线遗漏」，不是"上游也这样"）：
     *   1. **hover 保活**（契约 §3.6）：鼠标从触发元素移进浮层时，浮层的
     *      `onMouseenter` 要排一个开启定时器去顶掉 `onMouseleave` 排的关闭定时器；
     *      判定用的是 `popupRef.value.contains(event.target)` ⇒ 恒 null 就永不保活，
     *      表现为"鼠标一移过去浮层就消失"。
     *   2. **点浮层内不算外部点击**（§3.10）：`inPopupOrChild()` 用它判定，
     *      恒 null 会把浮层内部的点击当成外部点击而关闭（click 型浮层直接失效）。
     *
     * ⚠️ 别改成"只写 popupEle"—— 那正是这个 bug 的成因。
     */
    const setPopupEle = (element: HTMLElement | null): void => {
      popupEle.value = element;
      overlay.popupRef.value = element;
    };
    const offsetInfo = ref<OffsetInfo>({
      ready: false,
      offsetX: 0,
      offsetY: 0,
      offsetR: 0,
      offsetB: 0,
      arrowX: 0,
      arrowY: 0,
      scaleX: 1,
      scaleY: 1,
      // rc 初始 state 的 align 就是 builtinPlacements[placement] —— placement 类名
      // 不依赖首次对齐成功（jsdom 无布局 ⇒ isVisible 恒 false ⇒ 对齐早退）
      align: props.builtinPlacements[props.placement] ?? {},
    });
    const flipMemory = ref<FlipMemory>({});
    /** stretch='minWidth' 的目标宽度（对齐时量测，rc 的 stretchStyle）。 */
    const stretchMinWidth = ref('');
    const alignCount = ref(0);

    const isMobile = false; // v1 无 mobile 形态（tooltip / dropdown 都没有）

    /**
     * ⭐ 触发元素的**唯一**写入口 —— 写入前先归一成 DOM 元素。
     *
     * 🚨 **为什么必须归一**：`overlay.targetRef` 的契约是 `Ref<HTMLElement | null>`
     * （`use-overlay.ts` 头注「绑到触发元素上」）。但 Vue 的 ref 在 **child 是组件
     * vnode** 时给的是**组件实例**（`ComponentPublicInstance`），不是元素 ——
     * `ColorPicker` 的 `ColorTrigger`、`Button` 触发器等**全是这种形态**。
     * 直接存实例的后果（2026-10-16 实测）：
     *   · overlay 的 `inPopupOrChild()` 调 `containsOrIs(target, ele)` ⇒
     *     `host.contains` 不存在 ⇒ **抛 TypeError** ⇒ 外部点击处理器整体崩掉
     *     ⇒ 「点浮层外面不关闭」（ColorPicker / 一切组件触发器的浮层）。
     *   · `getPopupContainer(target)` 拿到的也不是元素。
     *
     * ⚠️ 别把归一逻辑只放在读取侧（本文件的 `targetElement`）：overlay 自己也会
     *    直接读 `targetRef`，那里读到的仍是实例。
     */
    const setTargetEle = (value: unknown): void => {
      overlay.targetRef.value = resolveTriggerElement(value);
    };

    /**
     * 对齐目标：alignPoint 场景用鼠标位置，否则用触发元素。
     *
     * ⚠️ 直接别名即可 —— `setTargetEle` 是唯一写入口且已归一 ⇒ `targetRef` 恒为元素。
     *    （此前这里还做一遍 `$el` 归一是**不够**的：overlay 自己读的是 `targetRef`。）
     */
    const targetElement = overlay.targetRef;

    const alignTarget = computed<HTMLElement | readonly [number, number] | null>(() => {
      if (props.alignPoint && overlay.mousePos.value) {
        return overlay.mousePos.value;
      }
      return targetElement.value;
    });

    const onAlign = (): void => {
      const ele = popupEle.value;
      const tgt = alignTarget.value;
      if (!ele || !tgt || !mergedOpen.value || isMobile) {
        return;
      }
      // rc：placementInfo = builtinPlacements[placement] 与 popupAlign 浅合并
      const placementInfo: TriggerAlign = {
        ...(props.builtinPlacements[props.placement] ?? {}),
        ...props.popupAlign,
      };
      const result = measureAlign({
        popupEle: ele,
        target: tgt,
        // This mode measures both scroll and viewport areas. The geometry
        // engine chooses how to use them from the actual placement below.
        htmlRegion: 'visibleFirst',
      });
      if (!result) {
        return;
      }
      /**
       * 🚨 目标完全在可视区外时**不要对齐**（2026-10-22 Menu 审计 M-06）。
       *
       * 页面刚加载时，下方菜单的 trigger 仍在视口外，但 `isVisible()` 只判
       * display/visibility（不判视口相交）⇒ 会照常对齐；此时 `alignPopup` 判定
       * 「浮层下边超出视口」并写下 `flip.bt`。**翻转记忆是粘滞的**：用户随后
       * 滚动到菜单时，即使位置已经正确，也会保持翻转 ⇒ 弹层永久偏移
       * （实测 140px = 180 - 40，正好是 popup 高度与 title 高度之差）。
       *
       * 修正：视口外不产生任何对齐结果，等滚动进视口后按**无记忆**的初始状态
       * 重新对齐。jsdom 的矩形恒为 0 ⇒ 不触发该分支，既有单测不受影响。
       */
      if (isHTMLElement(tgt) && isTargetOutsideArea(tgt.getBoundingClientRect(), result.check)) {
        return;
      }
      const outcome: AlignOutcome = alignPopup(
        {
          target: result.target,
          popup: result.popup,
          visible: result.check,
          scroll: result.visible,
          scaleX: result.scaleX,
          scaleY: result.scaleY,
        },
        placementInfo,
        flipMemory.value,
      );
      flipMemory.value = outcome.flip;
      // Keep the request unchanged while exposing the engine's effective placement.
      const effectiveAlign: TriggerAlign = { ...placementInfo, points: outcome.points };

      // ── stretch（rc-trigger 的 stretchStyle：'minWidth' ⇒ 浮层 min-width = 目标宽）──
      // 用 getBoundingClientRect（rc 同款，**不取整** —— offsetWidth 的整数化会让
      // 浮层宽 1px 偏移、L6 逐像素红）。
      if (props.stretch === 'minWidth' && isHTMLElement(tgt)) {
        stretchMinWidth.value = `${tgt.getBoundingClientRect().width}px`;
      }

      // ── offsetR/B（rc useAlign 尾部公式，AlignOutcome 不含）──
      // rc 用**未 floor** 的原始 offsetX 参与 offsetR/B；alignPopup 已 floor
      // （scale=1 时等价，scale≠1 时亚像素差，见文件头差异 2）。
      const rawOffsetX = outcome.offsetX * result.scaleX;
      const rawOffsetY = outcome.offsetY * result.scaleY;
      let offsetX4Right =
        result.mirror.x + result.mirror.width - result.popup.x - (rawOffsetX + result.popup.width);
      let offsetY4Bottom =
        result.mirror.y +
        result.mirror.height -
        result.popup.y -
        (rawOffsetY + result.popup.height);
      if (result.scaleX === 1) {
        offsetX4Right = Math.floor(offsetX4Right);
      }
      if (result.scaleY === 1) {
        offsetY4Bottom = Math.floor(offsetY4Bottom);
      }

      offsetInfo.value = {
        ready: true,
        offsetX: outcome.offsetX,
        offsetY: outcome.offsetY,
        offsetR: offsetX4Right / result.scaleX,
        offsetB: offsetY4Bottom / result.scaleY,
        arrowX: outcome.arrowX,
        arrowY: outcome.arrowY,
        scaleX: result.scaleX,
        scaleY: result.scaleY,
        align: effectiveAlign,
      };
      props.onPopupAlign?.(ele, effectiveAlign);
    };

    /** 合帧：同一 tick 内多次触发只对齐一次（rc 的 alignCountRef 协议）。 */
    const triggerAlign = (): void => {
      alignCount.value += 1;
      const id = alignCount.value;
      void Promise.resolve().then(() => {
        if (alignCount.value === id) {
          onAlign();
        }
      });
    };

    // ready 重置：placement 变化、open→false（rc 的两个 resetReady effect）
    watch(
      () => props.placement,
      () => {
        offsetInfo.value = {
          ...offsetInfo.value,
          ready: false,
          align: props.builtinPlacements[props.placement] ?? {},
        };
        flipMemory.value = {};
      },
    );
    watch(mergedOpen, (open) => {
      if (!open) {
        offsetInfo.value = { ...offsetInfo.value, ready: false };
        flipMemory.value = {};
      }
    });

    // Observe the actual target and popup scroll chains while open. Shadow-root
    // scroll events need their own listener; the owner window supplies resize.
    watch(
      [
        popupEle,
        targetElement,
        mergedOpen,
        () => props.getPopupContainer,
        () => {
          const target = targetElement.value;
          return target ? props.getPopupContainer?.(target) : undefined;
        },
      ],
      ([popup, target, open], _prev, onCleanup) => {
        if (!popup || !open || isMobile) return;
        let active = true;
        let release: (() => void) | undefined;
        onCleanup(() => {
          active = false;
          release?.();
        });
        // Portal moves its existing subtree after this parent's update. Observe
        // the actual new ancestors and measure only after that move completes.
        void nextTick(() => {
          if (!active) return;
          const scrollers = new Set([
            ...collectScroller(popup),
            ...(target ? collectScroller(target) : []),
          ]);
          const onScroll = () => {
            if (mergedOpen.value && props.alignPoint) {
              overlay.setOpen(false);
              return;
            }
            triggerAlign();
          };
          for (const scroller of scrollers) {
            scroller.addEventListener('scroll', onScroll, true);
          }
          const win = popup.ownerDocument.defaultView;
          win?.addEventListener('scroll', onScroll, true);
          win?.addEventListener('resize', triggerAlign);
          release = () => {
            for (const scroller of scrollers) {
              scroller.removeEventListener('scroll', onScroll, true);
            }
            win?.removeEventListener('scroll', onScroll, true);
            win?.removeEventListener('resize', triggerAlign);
          };
          triggerAlign();
        });
      },
      { flush: 'post' },
    );

    // 当前 placement/align 也可能由主题或响应式配置更新；在 DOM 更新后量测。
    watch(
      [
        () => props.placement,
        () => props.builtinPlacements[props.placement],
        () => props.popupAlign,
        () => overlay.mousePos.value,
      ],
      () => triggerAlign(),
      { deep: true, flush: 'post' },
    );
    // popupEle 挂上后补一次对齐（supportMotion=false 的简化队列不走 onPrepare）
    watch([popupEle, mergedOpen], () => {
      if (mergedOpen.value && popupEle.value) triggerAlign();
    });

    watch(
      [popupEle, targetElement, mergedOpen],
      ([popup, target, open], _previous, onCleanup) => {
        if (!popup || !open || isMobile) return;
        const ResizeObserverImpl = popup.ownerDocument.defaultView?.ResizeObserver;
        if (!ResizeObserverImpl) return;
        const observer = new ResizeObserverImpl(() => triggerAlign());
        observer.observe(popup, { box: 'border-box' });
        if (target) observer.observe(target, { box: 'border-box' });
        onCleanup(() => observer.disconnect());
      },
      { flush: 'post' },
    );

    // ============================ Motion hooks ======================
    // appear/enter 的 prepare ⇒ 先对齐再放行动画（首帧定位先于动画）。
    const motionHooks = {
      onAppearPrepare: (element: Element | null) => {
        if (isHTMLElement(element) && !popupEle.value) setPopupEle(element);
        onAlign();
      },
      onEnterPrepare: (element: Element | null) => {
        if (isHTMLElement(element) && !popupEle.value) setPopupEle(element);
        onAlign();
      },
    };
    const onMotionVisibleChanged = (visible: boolean): void => {
      inMotion.value = false;
      onAlign();
      props.afterOpenChange?.(visible);
    };

    expose({
      forceAlign: () => {
        if (!inMotion.value) {
          onAlign();
        }
      },
      nativeElement: () => targetElement.value,
      popupElement: () => popupEle.value,
    });

    // ============================ Render ============================
    const offsetStyle = computed<Record<string, string | number>>(() => {
      const AUTO = 'auto';
      const info = offsetInfo.value;
      // rc `useOffsetStyle`：`if (!isMobile && (ready || !open))` 才使用 offset。
      // 关闭时必须沿用**最后一次** offset，否则离场动画会在 -1000vw/-1000vh
      // 的屏外位置播放（2026-10-21 阶段 0 实测）。只有「打开但尚未对齐」才占位。
      if (!info.ready && mergedOpen.value) {
        return { left: '-1000vw', top: '-1000vh', right: AUTO, bottom: AUTO };
      }
      const points = info.align.points ?? '';
      const dynamicInset = (info.align as { dynamicInset?: boolean }).dynamicInset === true;
      // rc useOffsetStyle：dynamicInset 看 **popup 侧** point 的 LR/TB 字符
      const alignRight = dynamicInset && points[0]?.[1] === 'r';
      const alignBottom = dynamicInset && points[0]?.[0] === 'b';
      const style: Record<string, string | number> = {};
      if (alignRight) {
        style.right = `${info.offsetR}px`;
        style.left = AUTO;
      } else {
        style.left = `${info.offsetX}px`;
        style.right = AUTO;
      }
      if (alignBottom) {
        style.bottom = `${info.offsetB}px`;
        style.top = AUTO;
      } else {
        style.top = `${info.offsetY}px`;
        style.bottom = AUTO;
      }
      return style;
    });

    const alignedClassName = computed(() =>
      getAlignPopupClassName(
        props.builtinPlacements,
        props.prefixCls,
        offsetInfo.value.align,
        false,
      ),
    );

    /** 箭头内联定位（rc Popup/Arrow.js 的 autoArrow 分支）。 */
    const arrowStyle = computed<Record<string, string | number>>(() => {
      const info = offsetInfo.value;
      const style: Record<string, string | number> = { position: 'absolute' };
      const points = info.align.points;
      if (!points) return style;
      // points = [popupPoint('bl' 这类两字符), targetPoint] —— Arrow.js 的拆法
      const popupTB = points[0][0] ?? '';
      const popupLR = points[0][1] ?? '';
      const targetTB = points[1][0] ?? '';
      const targetLR = points[1][1] ?? '';
      if (popupTB === targetTB || !['t', 'b'].includes(popupTB)) {
        style.top = `${info.arrowY}px`;
      } else if (popupTB === 't') {
        style.top = 0;
      } else {
        style.bottom = 0;
      }
      if (popupLR === targetLR || !['l', 'r'].includes(popupLR)) {
        style.left = `${info.arrowX}px`;
      } else if (popupLR === 'l') {
        style.left = 0;
      } else {
        style.right = 0;
      }
      return style;
    });

    /** rc PopupContent：`memo(_, next => next.cache)` —— 关闭且非 fresh 时冻结内容。 */
    const contentSource = computed<VNodeChild>(() =>
      typeof props.popup === 'function' ? (props.popup as () => VNodeChild)() : props.popup,
    );
    const lastContent = shallowRef<VNodeChild>(undefined);
    watch(
      contentSource,
      (v) => {
        if (mergedOpen.value || props.fresh) {
          lastContent.value = v;
        }
      },
      // flush: post —— 改 lastContent 不能发生在渲染期（渲染自身依赖 ⇒ 递归更新），
      // 开启期间每次渲染后同步一份；关闭后不再更新 ⇒ 冻结
      { immediate: true, flush: 'post' },
    );
    const renderedContent = computed<VNodeChild>(() =>
      mergedOpen.value || props.fresh ? contentSource.value : lastContent.value,
    );

    const renderPopup = (): VNode => {
      const info = offsetInfo.value;
      const arrow = props.arrow;
      const motionName = props.motion?.motionName;
      return h(
        Portal,
        {
          open: props.forceRender || mergedOpen.value || inMotion.value,
          autoDestroy: props.destroyOnHidden ?? false,
          ...(props.getPopupContainer
            ? {
                getContainer: () => {
                  const tgt = overlay.targetRef.value;
                  return (tgt ? props.getPopupContainer?.(tgt) : undefined) ?? document.body;
                },
              }
            : {}),
        },
        {
          default: () =>
            h(
              CSSMotion,
              {
                visible: mergedOpen.value,
                motionName,
                motionAppear: true,
                motionEnter: true,
                motionLeave: true,
                motionDeadline: props.motion?.motionDeadline ?? 0,
                removeOnLeave: false,
                leavedClassName: `${props.prefixCls}-hidden`,
                forceRender: props.forceRender,
                hooks: motionHooks,
                onVisibleChanged: onMotionVisibleChanged,
                ...(props.motion?.supportMotion !== undefined
                  ? { supportMotion: props.motion.supportMotion }
                  : {}),
              },
              {
                default: (motion: {
                  className?: string;
                  style?: Record<string, string | number>;
                }) => {
                  return h(
                    'div',
                    mergeProps(
                      {
                        ref: ((el: unknown) => {
                          setPopupEle((el as HTMLElement | null) ?? null);
                        }) as never,
                        class: [
                          props.prefixCls,
                          motion.className,
                          ...(props.popupClassName
                            ? Array.isArray(props.popupClassName)
                              ? props.popupClassName
                              : [props.popupClassName]
                            : []),
                          !isMobile && alignedClassName.value,
                        ],
                        style: {
                          ...popupThemeStyle.value,
                          '--arrow-x': `${info.arrowX || 0}px`,
                          '--arrow-y': `${info.arrowY || 0}px`,
                          ...offsetStyle.value,
                          // rc 的 stretchStyle：'minWidth' ⇒ 浮层不窄于目标
                          ...(props.stretch === 'minWidth' && stretchMinWidth.value
                            ? { minWidth: stretchMinWidth.value }
                            : {}),
                          // rc miscStyle：关闭时指针穿透（离场动画期间仍占位）
                          ...(mergedOpen.value ? {} : { pointerEvents: 'none' }),
                          boxSizing: 'border-box',
                          zIndex: props.zIndex,
                          ...props.popupStyle,
                          ...(motion.style ?? {}),
                        },
                      },
                      props.popupAttrs ?? {},
                      overlay.popupProps.value,
                    ),
                    [
                      arrow
                        ? h(
                            'div',
                            {
                              class: [`${props.prefixCls}-arrow`, arrow.className],
                              style: { ...arrowStyle.value, ...(arrow.style ?? {}) },
                            },
                            arrow.content ?? undefined,
                          )
                        : null,
                      renderedContent.value,
                    ],
                  );
                },
              },
            ),
        },
      );
    };

    return () => {
      // 触发元素：default slot 的首个 vnode；非元素 / fragment 包一层 span（rc 同款）。
      const children = slots.default?.();
      const first = Array.isArray(children) ? children[0] : children;
      const child =
        first && typeof first === 'object' && 'type' in first
          ? (first as VNode)
          : h(
              'span',
              [first as VNodeChild].filter((c) => c !== null && c !== undefined),
            );

      const triggerNode = cloneVNode(
        child,
        {
          ...attrs,
          ...overlay.targetProps.value,
          // 🚨 不能写 `ref: overlay.targetRef`：组件 vnode 的 ref 给的是实例，
          //    会让 overlay 的 `inPopupOrChild()` 抛 TypeError ⇒ 外部点击不关闭。
          ref: setTargetEle as never,
        },
        // mergeRef=true：child 自己的 ref 与 targetRef 合并（rc 的 useComposeRef）
        true,
      );

      // rc 返回 Fragment [triggerNode, Popup] —— Vue 用数组同构，不包多余节点
      return [triggerNode, renderPopup()] as unknown as VNode;
    };
  },
});

export default Trigger;
```

## 高亮边距 (gap)

使用 `gap` 参数来控制高亮区域的边距和圆角。

- 支持 `gap.offset` 传数组类型，单独设置两个方向上的边距。

### gap.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/gap.tsx
import { Button, Col, Row, Slider, Space, Tour, Typography } from '@apollo-design/ui';
import { ref } from 'vue';

const { Text } = Typography;

const tourNode = ref<HTMLElement | null>(null);
const radius = ref(8);
const offsetX = ref(2);
const offsetY = ref(2);
const offset = ref(2);
const open = ref(false);
const offsetDirection = ref<'both' | 'individual'>('individual');

const steps = [
  {
    title: 'Upload File',
    description: 'Put your files here.',
    target: () => tourNode.value,
  },
];
</script>

<template>
  <div ref="tourNode">
    <Button type="primary" @click="open = true">Begin Tour</Button>
    <Space style="display: flex; margin-top: 12px" orientation="vertical">
      <Row :gutter="[8, 8]" align="middle">
        <Col :xs="24" :sm="8"><Text>Radius:</Text></Col>
        <Col :xs="24" :sm="16">
          <Slider v-model:value="radius" :min="0" :max="50" aria-label-for-handle="Radius" />
        </Col>
      </Row>
      <Row :gutter="[8, 8]" align="middle">
        <Col :xs="24" :sm="8"><Text>offset:</Text></Col>
        <Col :xs="24" :sm="16">
          <Slider v-model:value="offset" :min="0" :max="50" aria-label-for-handle="Offset" @focusin="offsetDirection = 'both'" @change="offsetDirection = 'both'" />
        </Col>
      </Row>
      <Row :gutter="[8, 8]" align="middle">
        <Col :xs="24" :sm="8"><Text>Horizontal offset:</Text></Col>
        <Col :xs="24" :sm="16">
          <Slider v-model:value="offsetX" :min="0" :max="50" aria-label-for-handle="Horizontal offset" @focusin="offsetDirection = 'individual'" @change="offsetDirection = 'individual'" />
        </Col>
      </Row>
      <Row :gutter="[8, 8]" align="middle">
        <Col :xs="24" :sm="8"><Text>Vertical offset:</Text></Col>
        <Col :xs="24" :sm="16">
          <Slider v-model:value="offsetY" :min="0" :max="50" aria-label-for-handle="Vertical offset" @focusin="offsetDirection = 'individual'" @change="offsetDirection = 'individual'" />
        </Col>
      </Row>
    </Space>
    <Tour
      :open="open"
      :steps="steps"
      :gap="
        offsetDirection === 'both'
          ? { offset, radius }
          : { offset: [offsetX, offsetY], radius }
      "
      @close="open = false"
    />
  </div>
</template>
```

## 面板预览 (render-panel)

静态面板（debug 用，`TourPurePanel` = antd 的 `_InternalPanelDoNotUseOrYouWillBeFired`）。

### render-panel.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/render-panel.tsx：PurePanel 静态面板（debug-only）
import { TourPurePanel } from '@apollo-design/ui';
</script>

<template>
  <div
    style="
      display: flex;
      flex-direction: column;
      row-gap: 16px;
      background: rgba(50, 0, 0, 0.65);
      padding: 8px;
    "
  >
    <TourPurePanel title="Hello World!" description="Hello World?!" />
    <TourPurePanel title="Hello World!" description="Hello World?!" :current="5" :total="7">
      <template #cover>
        <img
          draggable="false"
          alt="tour.png"
          src="https://user-images.githubusercontent.com/5378891/197385811-55df8480-7ff4-44bd-9d43-a7dade598d70.png"
        />
      </template>
    </TourPurePanel>
    <TourPurePanel
      title="Hello World!"
      description="Hello World?!"
      type="primary"
      :current="4"
      :total="5"
    />
  </div>
</template>
```

## 自定义样式与类名 (style-class)

`styles` / `classNames` 支持对象与函数两种形态；`styles` 传函数时入参含 `props`，可按组件形态（如 `type="primary"`）返回不同样式。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd demo/style-class.tsx：styles 对象形态 + 函数形态 + classNames + arrow=false
// ⚠️ createStaticStyles(css``) 是 antd-style 的产物，本仓直接用等价的普通对象。
import { Button, Divider, Flex, Space, Tour } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
const openFn = ref(false);

const ref1 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref2 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);
const ref3 = ref<{ nativeElement: HTMLButtonElement | HTMLAnchorElement | null } | null>(null);

const target1 = () => ref1.value?.nativeElement;
const target2 = () => ref2.value?.nativeElement;
const target3 = () => ref3.value?.nativeElement;

const btnProps = {
  nextButtonProps: {
    style: {
      border: '1px solid #CDC1FF',
      color: '#CDC1FF',
    },
  },
  prevButtonProps: {
    style: {
      backgroundColor: '#CDC1FF',
      color: '#fff',
    },
  },
};

const classNames = {
  root: 'tour-demo-root-radius',
  section: 'tour-demo-section-radius',
};

const stylesObject = {
  mask: {
    backgroundColor: 'rgba(0, 0, 0, 0.3)',
  },
  section: {
    boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
    border: '2px solid #4096ff',
  },
  cover: {
    borderRadius: '12px 12px 0 0',
  },
};

const stylesFunction = (info: { props: { type?: string } }) => {
  if (info.props.type === 'primary') {
    return {
      mask: {
        backgroundColor: 'rgba(0, 0, 0, 0.3)',
      },
      section: {
        backgroundColor: 'rgb(205,193,255, 0.8)',
        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
      },
      cover: {
        borderRadius: '12px 12px 0 0',
      },
    };
  }
  return {};
};

const steps = [
  {
    title: 'Upload File',
    description: 'Put your files here.',
    target: target1,
    prevButtonProps: {},
  },
  {
    title: 'Save',
    description: 'Save your changes.',
    target: target2,
  },
  {
    title: 'Other Actions',
    description: 'Click to see other actions.',
    target: target3,
  },
];

const sharedProps = {
  steps,
  classNames,
  arrow: false,
};
</script>

<template>
  <Flex vertical gap="medium">
    <Flex wrap gap="medium">
      <Button type="primary" @click="open = true">Begin Tour Object</Button>
      <Button type="primary" @click="openFn = true">Begin Tour Function</Button>
    </Flex>
    <Divider />
    <Tour
      :steps="sharedProps.steps"
      :class-names="sharedProps.classNames"
      :arrow="false"
      :open="open"
      :styles="stylesObject"
      @close="open = false"
    >
      <template #cover="{ current }">
        <img
          v-if="current === 0"
          alt="tour.png"
          src="https://user-images.githubusercontent.com/5378891/197385811-55df8480-7ff4-44bd-9d43-a7dade598d70.png"
        />
      </template>
    </Tour>
    <Tour
      :steps="steps.map((s) => ({ ...s, ...btnProps }))"
      :class-names="sharedProps.classNames"
      :arrow="false"
      type="primary"
      :open="openFn"
      :styles="stylesFunction"
      @close="openFn = false"
    >
      <template #cover="{ current }">
        <img
          v-if="current === 0"
          alt="tour.png"
          src="https://user-images.githubusercontent.com/5378891/197385811-55df8480-7ff4-44bd-9d43-a7dade598d70.png"
        />
      </template>
    </Tour>
    <Space wrap>
      <Button ref="ref1" type="primary">Upload</Button>
      <Button ref="ref2">Save</Button>
      <Button ref="ref3" type="dashed">Other Actions</Button>
    </Space>
  </Flex>
</template>
```

---

# Transfer

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/transfer


# Transfer 穿梭框

双栏穿梭选择框。

## 何时使用

- 需要在两组数据之间进行选择和移动时；
- 需要对选项进行批量移动（全选 / 反选 / 按页选择）时；
- 需要搜索过滤、分页浏览大量候选项时。

## 引入

```ts
import { Transfer } from '@apollo-design/ui';
```

## 代码演示


















## API

### Transfer

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| dataSource | 数据源，条目需含 `key` | `TransferItem[]` | `[]` |
| targetKeys (`v-model:targetKeys`) | 右列 key；传入时受控，未绑定时内部维护 | `TransferKey[]` | `[]` |
| selectedKeys (`v-model:selectedKeys`) | 勾选 key；传入时受控，未绑定时内部维护 | `TransferKey[]` | - |
| titles | 左右列标题 | `VNodeChild[]` | `['', '']` |
| actions | 自定义操作按钮文案 `[向右, 向左]` | `VNodeChild[]` | 箭头图标 |
| operations | 同 `actions`（deprecated） | `VNodeChild[]` | - |
| locale | 文案 | `TransferLocale` | en_US |
| disabled | 整体禁用 | `boolean` | `false` |
| showSearch | 显示搜索框（对象形态可给 `defaultValue` / `placeholder`） | `boolean \| { defaultValue?: string; placeholder?: string }` | `false` |
| showSelectAll | 显示头部全选区 | `boolean` | `true` |
| oneWay | 单向模式（隐藏向左按钮、右列渲染删除按钮） | `boolean` | `false` |
| pagination | 列表分页 | `boolean \| { pageSize?: number; simple?: boolean; showSizeChanger?: boolean; showLessItems?: boolean }` | - |
| status | 校验状态 | `'error' \| 'warning'` | - |
| selectionsIcon | 头部下拉的图标 | `VNodeChild` | `DownOutlined` |
| filterOption | 自定义搜索匹配 | `(inputValue, item, direction) => boolean` | 文本包含 |
| rowKey | 条目 key 取值器 | `(record) => TransferKey` | `record.key` |
| selectAllLabels | 逐列头部文案 | `[VNodeChild?, VNodeChild?]` | 计数文案 |
| listStyle | 面板外联样式（deprecated → `styles.section`） | `object \| ({ direction }) => object` | - |
| operationStyle | 操作区样式（deprecated → `styles.actions`） | `object` | - |
| classNames / styles | 语义化类名 / 样式（含 `source` / `target` 方向子结构） | `object` | - |

### 插槽

| 名称 | 作用域 | 默认行为 |
| --- | --- | --- |
| item | `{ item, direction, selected, disabled }` | 数据 `title`，非文本时回退 `key` |
| footer | `{ direction, selectedKeys, totalCount }` | 无底栏；`totalCount` 是该侧全部条目数 |
| list | `{ direction, filteredItems, selectedKeys, disabled, onItemSelect, onItemSelectAll, onItemRemove, onScroll }` | 默认列表；自定义列表不启用内嵌分页 |
| selectAllLabel | `{ direction, selectedCount, totalCount }` | `selectAllLabels` 静态数据或默认计数；计数基于筛选后的列表 |

插槽在渲染期读取，支持条件增删和动态内容；明确提供空 slot 不会回退。`direction` 是数据方向 `left/right`，RTL 不改变其含义。`#item` 的富内容不参与搜索解析；默认搜索、行 title 和 checkbox 名称取数据 `title/key`，其他搜索字段使用 `filterOption`。

`onItemSelect(key, selected)` 选择单项；`onItemSelectAll(keys, selected)` 的第二参支持 `true`、`false` 和 `'replace'`。选择函数过滤禁用或不属于当前筛选列表的键。`onItemRemove(keys)` 用于右侧单向移除，`onScroll(event)` 转发滚动事件。自定义控件仍需绑定 `disabled`。

当前开发版直接移除 `render`、`footer`、`renderList` / `children` 函数 props 及 `selectAllLabels` 函数项；使用以上插槽，没有旧函数兼容层或弃用期。完整变化见 `docs/migrations/transfer-slots.md`（ADR 0006）。

### 事件

| 事件 | 说明 | 回调参数 |
| --- | --- | --- |
| update:targetKeys | 请求更新目标 key，供 `v-model:targetKeys` 使用 | `(targetKeys)` |
| update:selectedKeys | 请求更新勾选 key，供 `v-model:selectedKeys` 使用 | `(selectedKeys)` |
| change | 请求移动时触发；受控数据以父组件接受结果为准 | `(targetKeys, direction, moveKeys)` |
| selectChange | 勾选变化 | `(sourceSelectedKeys, targetSelectedKeys)` |
| search | 搜索值变化（含清空） | `(direction, value)` |
| scroll | 列表滚动 | `(direction, event)` |

事件使用 Vue emits；模板监听与 `h()` 的监听器数组只通知一次，不会落到原生根上。撤除受控 prop 后保留最后接受的状态。Shift 范围只使用当前筛选列表的可用项，数据重排时按 key 定位选择锚点。

### 引用与原生属性

`TransferRef.nativeElement` 是当前根 `HTMLElement`，卸载后为 `null`；`focus(options?: FocusOptions)` 聚焦本实例第一个可用控件，`blur()` 只移除本实例内的焦点。原生 `class/style/id/data-*` 等落根，style 支持 Vue 的对象、字符串和数组；`styles` 的节点值为 `CSSProperties`。长度显式写单位；opacity 等无单位属性可用数值，遵循 Vue 原生样式语义。

### 静态属性

- `Transfer.List` / `TransferList`：列表面板（自定义列表面板 / 单面板使用）；
- `Transfer.Search` / `TransferSearch`：搜索框；
- `Transfer.Operation` / `TransferOperation`：操作按钮列。

静态成员与命名导出具有同一类型。`Transfer.Search` 的值支持 `v-model:value`，使用 `@change` / `@clear`；原 `handleClear` 改为 `@clear`。`Transfer.Operation` 使用 `@move-to-right` / `@move-to-left`，直接替代 `moveToRight/moveToLeft` 回调 props。`Transfer.List` 的过滤、清空、选择和移除使用对应 Vue 事件；原 `handleFilter/handleClear` 改为 `@filter/@clear`。

操作内容中的图标、文本和普通节点由所属按钮承载；实际自定义按钮保留 Vue 的 key、ref、指令和监听器数组，禁用时不触发移动。头部菜单由具名原生按钮打开，支持键盘 Enter。

## 主题变量

| Token | 说明 | 默认值 |
| --- | --- | --- |
| `listWidth` | 面板宽度 | `180px` |
| `listHeight` | 面板高度 | `200px` |
| `listWidthLG` | 分页下面板宽度 | `250px` |
| `headerHeight` | 面板头高度 | `40px` |
| `itemHeight` | 条目最小高度 | `32px` |
| `itemPaddingBlock` | 条目纵向内边距 | `5px` |
| `transferHeaderVerticalPadding` | 面板头纵向内边距 | `9px` |

通过 `ConfigProvider.theme.components.Transfer` 配置以上七项，数值长度转为 px，字符串保留 CSS 长度；当前主题替换、嵌套和撤除会更新派生值。原生和语义样式仍可覆盖这些变量；`listStyle` 的优先级低于 `styles.section`。


## 基本 (basic)

最简单的用法：勾选左列条目 → 点击「向右」按钮移动到目标列。

### basic.vue

```vue
<script setup lang="ts">
import type { TransferKey } from '@apollo-design/ui';
import { Transfer } from '@apollo-design/ui';
import { ref } from 'vue';

const mockData = Array.from({ length: 20 }, (_, i) => ({
  key: i.toString(),
  title: `content${i + 1}`,
  description: `description of content${i + 1}`,
  disabled: i % 4 === 0,
}));

const targetKeys = ref<TransferKey[]>(
  mockData.filter((item) => Number(item.key) % 3 > 1).map((item) => item.key),
);
const selectedKeys = ref<TransferKey[]>(['1', '4']);
</script>

<template>
  <Transfer
    :data-source="mockData"
    v-model:target-keys="targetKeys"
    v-model:selected-keys="selectedKeys"
  />
</template>
```

## 搜索 (search)

`showSearch` 开启搜索框，按条目文本过滤两个列表。

### search.vue

```vue
<script setup lang="ts">
// 对齐 antd `search.tsx`。
import type { TransferKey } from '@apollo-design/ui';
import { Transfer } from '@apollo-design/ui';
import { ref } from 'vue';

const mockData = Array.from({ length: 20 }, (_, i) => ({
  key: i.toString(),
  title: `content${i + 1}`,
  description: `description of content${i + 1}`,
}));

const targetKeys = ref<TransferKey[]>(
  mockData.filter((item) => Number(item.key) % 3 > 1).map((item) => item.key),
);

const handleChange = (newTargetKeys: TransferKey[]) => {
  targetKeys.value = newTargetKeys;
};
</script>

<template>
  <Transfer :data-source="mockData" show-search :target-keys="targetKeys" @change="handleChange" />
</template>
```

## 单向 (oneway)

`oneWay` 单向模式：隐藏「向左」按钮，右列改为删除按钮。

### oneway.vue

```vue
<script setup lang="ts">
// 对齐 antd `oneway.tsx`。
import type { TransferKey } from '@apollo-design/ui';
import { Transfer } from '@apollo-design/ui';
import { ref } from 'vue';

const mockData = Array.from({ length: 20 }, (_, i) => ({
  key: i.toString(),
  title: `content${i + 1}`,
  disabled: i % 4 === 0,
}));

const targetKeys = ref<TransferKey[]>(['2', '4']);

const handleChange = (newTargetKeys: TransferKey[]) => {
  targetKeys.value = newTargetKeys;
};
</script>

<template>
  <Transfer :data-source="mockData" one-way :target-keys="targetKeys" @change="handleChange" />
</template>
```

## 高级用法 (advanced)

受控 `selectedKeys` + `render` 自定义条目渲染的完整交互。

### advanced.vue

```vue
<script setup lang="ts">
// 对齐 antd `advanced.tsx`。
import type { TransferKey } from '@apollo-design/ui';
import { Transfer } from '@apollo-design/ui';
import { ref } from 'vue';

const mockData = Array.from({ length: 15 }, (_, i) => ({
  key: i.toString(),
  title: `content${i + 1}`,
  chosen: i % 2 === 0,
}));

const oriTargetKeys = mockData.filter((item) => item.chosen).map((item) => item.key);

const selectedKeys = ref<string[]>([]);
const targetKeys = ref<string[]>([...oriTargetKeys]);

const handleChange = (newTargetKeys: TransferKey[]) => {
  targetKeys.value = newTargetKeys.map(String);
};

const handleSelectChange = (
  sourceSelectedKeys: TransferKey[],
  targetSelectedKeys: TransferKey[],
) => {
  selectedKeys.value = [...sourceSelectedKeys, ...targetSelectedKeys].map(String);
};
</script>

<template>
  <Transfer
    :data-source="mockData"
    :target-keys="targetKeys"
    :selected-keys="selectedKeys"
    @change="handleChange"
    @select-change="handleSelectChange"
  />
</template>
```

## 分页 (pagination)

`pagination` 开启列表面板内嵌分页（面板自动加宽，头部下拉多出「选择当前页」）。

### pagination.vue

```vue
<script setup lang="ts">
// 对齐 antd `pagination.tsx`。
import type { TransferKey } from '@apollo-design/ui';
import { Transfer } from '@apollo-design/ui';
import { ref } from 'vue';

const mockData = Array.from({ length: 40 }, (_, i) => ({
  key: i.toString(),
  title: `content${i + 1}`,
  disabled: i % 4 === 0,
}));

const targetKeys = ref<string[]>(
  mockData.filter((item) => Number(item.key) % 3 > 1).map((item) => item.key),
);
</script>

<template>
  <Transfer
    :data-source="mockData"
    :pagination="{ pageSize: 10 }"
    :target-keys="targetKeys"
    @change="targetKeys = $event.map(String)"
  />
</template>
```

## 自定义渲染条目 (custom-item)

`#item` 渲染条目，`#footer` 展示面板统计。搜索匹配数据 `title`；自定义搜索使用 `filterOption`。

### custom-item.vue

```vue
<script setup lang="ts">
// 对齐 antd `custom-item.tsx`。
import type { TransferKey } from '@apollo-design/ui';
import { Transfer } from '@apollo-design/ui';
import { ref } from 'vue';

const mockData = Array.from({ length: 20 }, (_, i) => ({
  key: i.toString(),
  title: `content${i + 1}`,
  chosen: i % 2 === 0,
}));

const targetKeys = ref<string[]>(mockData.filter((item) => item.chosen).map((item) => item.key));
</script>

<template>
  <Transfer
    :data-source="mockData"
    :target-keys="targetKeys"
    @change="targetKeys = $event.map(String)"
  >
    <template #item="{ item, selected, disabled }">
      <span :aria-disabled="disabled">{{ item.title }}（key: {{ item.key }}）{{ selected ? ' ✓' : '' }}</span>
    </template>
    <template #footer="{ direction, selectedKeys, totalCount }">
      {{ direction === 'left' ? '来源' : '目标' }}：{{ selectedKeys.length }}/{{ totalCount }}
    </template>
  </Transfer>
</template>
```

## 校验状态 (status)

`status` 为面板边框增加 error / warning 校验态。

### status.vue

```vue
<script setup lang="ts">
// 对齐 antd `status.tsx`。
import { Transfer } from '@apollo-design/ui';
import { ref } from 'vue';

const mockData = Array.from({ length: 10 }, (_, i) => ({
  key: i.toString(),
  title: `content${i + 1}`,
}));

const targetKeys = ref<string[]>(['2', '4']);
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <Transfer :data-source="mockData" status="error" v-model:target-keys="targetKeys" />
    <Transfer :data-source="mockData" status="warning" v-model:target-keys="targetKeys" />
  </div>
</template>
```

## 自定义选择全部文案 (custom-select-all-labels)

`#selectAllLabel` 用方向和当前计数渲染文案；静态逐列文案也可用 `selectAllLabels` 数组。

### custom-select-all-labels.vue

```vue
<script setup lang="ts">
// 对齐 antd `custom-select-all-labels.tsx`。
import { Transfer } from '@apollo-design/ui';
import { ref } from 'vue';

const mockData = Array.from({ length: 10 }, (_, i) => ({
  key: i.toString(),
  title: `content${i + 1}`,
}));

const targetKeys = ref<string[]>(['2', '4']);
</script>

<template>
  <Transfer
    :data-source="mockData"
    v-model:target-keys="targetKeys"
  >
    <template #selectAllLabel="{ direction, selectedCount, totalCount }">
      {{ direction === 'left' ? `${selectedCount}/${totalCount} 条` : '已选列表' }}
    </template>
  </Transfer>
</template>
```

## 表格穿梭框 (table-transfer)

通过 `#list` 把左右两列交给 `Table` 渲染：勾选行与行点击都会回写 `selectedKeys`，
分页与 `rowKey` 走 Table 自身语义（对齐 antd `table-transfer.tsx`）。

### table-transfer.vue

```vue
<script lang="ts" setup>
import type {
  TableColumnsType,
  TableRowSelection,
  TransferItem,
  TransferKey,
  TransferListSlotProps,
} from '@apollo-design/ui';
import { Table, Transfer } from '@apollo-design/ui';
import { ref } from 'vue';

const mockData: TransferItem[] = Array.from({ length: 20 }, (_, i) => ({
  key: i.toString(),
  title: `content${i + 1}`,
  description: `description of content${i + 1}`,
  disabled: i % 4 === 0,
}));
const targetKeys = ref<TransferKey[]>(
  mockData.filter((item) => Number(item.key) % 3 > 1).map((item) => item.key),
);
const columns: TableColumnsType = [
  { title: 'Name', dataIndex: 'title' },
  { title: 'Description', dataIndex: 'description' },
];
const rowSelection = (scope: TransferListSlotProps): TableRowSelection => ({
  selectedRowKeys: scope.selectedKeys,
  getCheckboxProps: (record) => ({ disabled: scope.disabled || !!record.disabled }),
  onSelect: (record, selected) => {
    if (typeof record.key === 'string' || typeof record.key === 'number') {
      scope.onItemSelect(record.key, selected);
    }
  },
  onSelectAll: (selected, _selectedRows, changedRows) =>
    scope.onItemSelectAll(
      changedRows.flatMap((record) =>
        typeof record.key === 'string' || typeof record.key === 'number' ? [record.key] : [],
      ),
      selected,
    ),
});
</script>

<template>
  <Transfer :data-source="mockData" :target-keys="targetKeys" :show-select-all="false" class="table-transfer" @change="targetKeys = $event">
    <template #list="scope">
      <Table class="table-transfer-list" size="small" :columns="columns" :data-source="scope.filteredItems" row-key="key" :pagination="{ pageSize: 5 }" :row-selection="rowSelection(scope)" />
    </template>
  </Transfer>
</template>

<style scoped>
.table-transfer :deep(.table-transfer-list) { padding: 0 4px; width: 100%; height: 100%; }
</style>
```

## 树形穿梭框 (tree-transfer)

通过 `#list` 把左右两列交给 `Tree` 渲染：树形分组显示，节点独立勾选，勾选结果经
`onItemSelect` 逐个回写 `selectedKeys`。

### tree-transfer.vue

```vue
<script lang="ts" setup>
import type {
  TransferItem,
  TransferKey,
  TransferListSlotProps,
  TreeCheckedKeys,
} from '@apollo-design/ui';
import { Transfer, Tree } from '@apollo-design/ui';
import { ref } from 'vue';

interface TreeNode {
  key: TransferKey;
  title: string;
  disabled: boolean;
  children?: TreeNode[];
}

const transferDataSource: TransferItem[] = [
  { key: '0-0', title: '内容一' },
  { key: '0-1', title: '内容二' },
  { key: '0-1-0', title: '内容二一' },
  { key: '0-1-1', title: '内容二二' },
  { key: '0-2', title: '内容三' },
  { key: '0-3', title: '内容四' },
];
const targetKeys = ref<TransferKey[]>([]);
// Each panel contains its own filtered data. Grouping is visual; checkStrictly keeps transfer keys independent.
const treeData = (items: TransferItem[]): TreeNode[] => {
  const nodes: TreeNode[] = items.map((item) => ({
    key: item.key,
    title: String(item.title),
    disabled: !!item.disabled,
  }));
  const parent = nodes.find((node) => node.key === '0-1');
  if (!parent) return nodes;
  parent.children = nodes.filter((node) => String(node.key).startsWith('0-1-'));
  return nodes.filter((node) => !parent.children?.includes(node));
};
const select = (scope: TransferListSlotProps, keys: TransferKey[] | TreeCheckedKeys) => {
  scope.onItemSelectAll(Array.isArray(keys) ? keys : keys.checked, 'replace');
};
</script>

<template>
  <Transfer :data-source="transferDataSource" :target-keys="targetKeys" class="tree-transfer" @change="targetKeys = $event">
    <template #list="scope">
      <Tree class="tree-transfer-list" checkable check-strictly default-expand-all :disabled="scope.disabled" :tree-data="treeData(scope.filteredItems)" :checked-keys="scope.selectedKeys" @update:checked-keys="select(scope, $event)" />
    </template>
  </Transfer>
</template>

<style scoped>
.tree-transfer :deep(.tree-transfer-list) { padding: 8px; width: 100%; height: 100%; }
</style>
```

## 大数据 (large-data)

`dataSource` 提供 100 条数据，配合 `pagination`、`showSearch` 与 `showSelectAll` 完成大批量穿梭。

### large-data.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `large-data` demo：100 条数据 + 分页 + 搜索。
import type { TransferItem, TransferKey } from '@apollo-design/ui';
import { Text, Transfer } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const dataSource: TransferItem[] = Array.from({ length: 100 }, (_, i) => ({
  key: `item-${i}`,
  title: `Content ${i + 1}`,
  description: `Description of content ${i + 1}`,
  disabled: i % 17 === 0,
}));

const targetKeys = ref<TransferKey[]>(
  dataSource.filter((_, i) => i % 3 === 0).map((item) => item.key),
);

const targetCount = computed(() => targetKeys.value.length);

const onChange = (keys: TransferKey[]) => {
  targetKeys.value = keys;
};
</script>

<template>
  <div>
    <Transfer
      :data-source="dataSource"
      :target-keys="targetKeys"
      :pagination="{ pageSize: 10 }"
      :titles="['Source (100)', 'Target']"
      show-search
      show-select-all
      @change="onChange"
    />
    <div style="margin-top: 12px">
      <Text type="secondary">右侧 {{ targetCount }} 项；分页每页 10 条，可搜索筛选。</Text>
    </div>
  </div>
</template>
```

## 自定义操作 (actions)

通过 `actions` 传入箭头图标节点替换默认操作按钮，穿梭后右侧数量实时更新。

### actions.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `actions` demo：用箭头图标替换默认操作按钮文案。
import { ArrowLeftOutlined, ArrowRightOutlined } from '@apollo-design/icons';
import type { TransferKey } from '@apollo-design/ui';
import { Text, Transfer } from '@apollo-design/ui';
import { h, ref } from 'vue';

const dataSource = Array.from({ length: 12 }, (_, i) => ({
  key: String(i),
  title: `Content ${i + 1}`,
  description: `Description ${i + 1}`,
}));

const targetKeys = ref<TransferKey[]>(['2', '4']);
const actions = [h(ArrowRightOutlined), h(ArrowLeftOutlined)];

const onChange = (keys: TransferKey[]) => {
  targetKeys.value = keys;
};
</script>

<template>
  <div>
    <Transfer
      :data-source="dataSource"
      :target-keys="targetKeys"
      :actions="actions"
      show-search
      @change="onChange"
    />
    <div style="margin-top: 12px">
      <Text type="secondary">操作按钮使用 `actions` 自定义为箭头图标；当前右侧 {{ targetKeys.length }} 项。</Text>
    </div>
  </div>
</template>
```

## 组件 Token (component-token)

通过 `ConfigProvider.theme.components.Transfer` 设置七个有效 Token，切换按钮可撤除配置并恢复当前主题的派生值。目标列表使用 `v-model:targetKeys`。

### component-token.vue

```vue
<script setup lang="ts">
import type { ThemeConfig } from '@apollo-design/theme';
import type { TransferKey } from '@apollo-design/ui';
import { Button, ConfigProvider, Transfer } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const dataSource = Array.from({ length: 8 }, (_, index) => ({
  key: String(index),
  title: `Item ${index + 1}`,
  description: `Description ${index + 1}`,
}));

const targetKeys = ref<TransferKey[]>(['1', '3']);
const customized = ref(true);
const theme = computed((): ThemeConfig => {
  if (!customized.value) return {};
  return {
    components: {
      Transfer: {
        listWidth: 220,
        listHeight: 260,
        listWidthLG: 280,
        headerHeight: 48,
        itemHeight: 40,
        itemPaddingBlock: 8,
        transferHeaderVerticalPadding: 11,
      },
    },
  };
});
</script>

<template>
  <Button style="margin-bottom: 16px" @click="customized = !customized">{{ customized ? 'Restore defaults' : 'Apply tokens' }}</Button>
  <ConfigProvider :theme="theme">
    <Transfer
      :data-source="dataSource"
      v-model:target-keys="targetKeys"
      :titles="['Source', 'Target']"
    />
  </ConfigProvider>
</template>
```

## 语义化样式 (style-class)

通过 `classNames` 给面板、表头、条目与操作区加类，并用 `styles` 覆盖表头与条目的行内样式。

### style-class.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 style-class demo：用 classNames / styles 定制面板、表头与条目。
import type { TransferKey } from '@apollo-design/ui';
import { Transfer } from '@apollo-design/ui';
import { ref } from 'vue';

const dataSource = Array.from({ length: 6 }, (_, index) => ({
  key: String(index),
  title: `Item ${index + 1}`,
  description: `Description ${index + 1}`,
}));

const targetKeys = ref<string[]>(['2']);

const handleChange = (nextTargetKeys: TransferKey[]) => {
  targetKeys.value = nextTargetKeys.map(String);
};

const classNames = {
  section: 'demo-transfer-style-section',
  header: 'demo-transfer-style-header',
  item: 'demo-transfer-style-item',
  actions: 'demo-transfer-style-actions',
};

const styles = {
  header: { color: '#1677ff', fontWeight: '600' },
  item: { fontStyle: 'italic' },
};
</script>

<template>
  <div class="demo-transfer-style-root">
    <Transfer
      :data-source="dataSource"
      :target-keys="targetKeys"
      :titles="['Source', 'Target']"
      :class-names="classNames"
      :styles="styles"
      @change="handleChange"
    />
  </div>
</template>

<style>
.demo-transfer-style-root .demo-transfer-style-section {
  border-color: #91caff;
  border-radius: 12px;
}

.demo-transfer-style-root .demo-transfer-style-header {
  letter-spacing: 0.04em;
}

.demo-transfer-style-root .demo-transfer-style-item {
  color: #531dab;
}

.demo-transfer-style-root .demo-transfer-style-actions {
  gap: 12px;
}
</style>
```

---

# Tree

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/tree


# Tree 树形控件

多层结构的数据（文件夹、组织架构等）以树形展开，支持选择、勾选、异步加载、拖拽与虚拟滚动。

## 何时使用

- 树形层级数据展示与导航；
- 需要对层级数据进行选择 / 勾选（级联或严格模式）；
- 大数据量时开启虚拟滚动；目录结构场景直接使用 `DirectoryTree`。

## 引入

```ts
import { Tree, DirectoryTree } from '@apollo-design/ui';
```

## 代码演示































## API

### TreeProps

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| treeData | 树数据；字段可用 fieldNames 映射，默认 key/title/children | object[]（可用 `TreeProps<T>` 声明数据类型） | - |
| fieldNames | 字段名映射 | { key?, title?, children? } | - |
| expandedKeys | 展开节点（受控，`v-model:expandedKeys`） | TreeKey[] | - |
| defaultExpandedKeys | 默认展开 | TreeKey[] | [] |
| defaultExpandAll | 默认展开全部（**只展开有 children 的节点**） | boolean | false |
| defaultExpandParent | 默认展开父节点（首挂 conductExpandParent 补祖先） | boolean | true |
| autoExpandParent | 展开受控时自动补全祖先 | boolean | false |
| checkable | 勾选（自定义勾选框） | boolean \| VNodeChild | false |
| checkStrictly | 父子独立勾选；事件返回 `{ checked, halfChecked }`，不决定是否受控 | boolean | false |
| checkedKeys | 勾选节点（受控，`v-model:checkedKeys`） | SafeKey[] \| { checked, halfChecked } | - |
| defaultCheckedKeys | 默认勾选 | SafeKey[] | [] |
| selectable | 可选中 | boolean | true |
| multiple | 支持多选 | boolean | false |
| selectedKeys | 选中节点（受控，`v-model:selectedKeys`） | TreeKey[] | - |
| defaultSelectedKeys | 默认选中 | TreeKey[] | - |
| loadData | 异步加载 | (node) => Promise | - |
| loadedKeys | 已加载节点（受控，`v-model:loadedKeys`） | SafeKey[] | - |
| showIcon | 显示节点图标 | boolean | false |
| showLine | 连接线 | boolean \| { showLeafIcon } | false |
| icon | 节点图标内容；动态内容用 `#icon` | VNodeChild | - |
| switcherIcon | 展开按钮图标内容；动态内容用 `#switcherIcon` | VNodeChild | - |
| switcherLoadingIcon | 加载中图标 | VNodeChild | - |
| blockNode | 节点占满一行 | boolean | false |
| expandAction | 点击/双击节点时触发展开 | false \| 'click' \| 'doubleClick' | false |
| disabled | 整棵树禁用 | boolean | - |
| draggable | 可拖拽 | boolean \| fn \| { nodeDraggable?, icon? } | false |
| allowDrop | 是否允许拖入 | (options) => boolean | () => true |
| height | 虚拟滚动容器高度 | number | - |
| itemHeight | 虚拟列表估算行高，默认 paddingXS/2 + titleHeight | number | - |
| scrollWidth | 横向滚动宽度 | number | - |
| virtual | 虚拟滚动（默认读 ConfigProvider） | boolean | - |
| itemScrollOffset | activeKey 滚动跟随附加偏移 | number | 0 |
| focusable | 可聚焦 | boolean | true |
| activeKey | 键盘活动节点（`v-model:activeKey`，null 清空） | TreeKey \| null | - |
| filterTreeNode | 过滤命中节点（`-filter-node` 类） | (node) => boolean | - |
| tabIndex | 树焦点宿主的 tabindex | number | 0 |
| prefixCls | DOM 类前缀（需配套静态 CSS） | string | apollo-tree |
| classNames / styles | root、item、itemIcon、itemTitle、itemSwitcher 语义区域；支持 `{ props }` 函数 | object \| function | - |
| rootStyle | 根样式（建议使用原生 style） | CSSProperties | - |

### 事件（Emits）

`expandedKeys`、`checkedKeys`、`selectedKeys`、`loadedKeys` 的更新分别同时发送 `update:*` 和 `expand`、`check`、`select`、`load`。`activeKey` 同时发送 `update:activeKey` 和 `activeChange`。

| 事件 | 参数 |
| --- | --- |
| expand | (keys, { node, expanded, nativeEvent: MouseEvent \| KeyboardEvent }) |
| check | (keysOrObject, { event: 'check', node, checked, checkedNodes, checkedNodesPositions?, halfCheckedKeys?, nativeEvent }) |
| select | (keys, { event: 'select', node, selected, selectedNodes, nativeEvent }) |
| load | (keys, { event: 'load', node }) |
| activeChange | (key: TreeKey \| null) |
| click / doubleClick / contextmenu / mouseEnter / mouseLeave | (event: MouseEvent, node) |
| dragStart / dragOver / dragLeave | (event: DragEvent, { node }) |
| dragEnter | (event: DragEvent, { node, expandedKeys }) |
| dragEnd | (event: DragEvent, { node: EventDataNode \| null })；在树外结束时 node 为 null |
| drop | (event: DragEvent, { node, dragNode, dragNodesKeys, dropPosition, dropToGap }) |

受控 prop 的每次更新都是请求；父级拒绝时，当前展示与撤控后的本地状态保留最后接受值。`multiple`、`checkStrictly`、能力与数据变化会重新投影当前键，纯派生不发送用户事件。`defaultExpandParent` 只影响初始化；`autoExpandParent` 是持续生效的祖先补全。

异步加载针对同一节点合并进行中的请求。完成但父级拒绝 `loadedKeys` 时不会自动再次请求；失败会报告警告，可通过下一次展开重试。替换或移除节点、卸载后的旧结果不更新状态。

### Slots

所有作用域均为 `{ node, data }`：node 含规范 key、展开/选择/勾选/加载/拖放状态，data 是原始数据对象（保留 fieldNames 对应字段）。插槽存在即优先，包括空内容。

| 插槽 | 说明 |
| --- | --- |
| title | 节点标题，优先于数据项 title（包括数据标题函数） |
| icon | showIcon 开启时的节点图标，优先于内容 prop 和数据图标 |
| switcherIcon | 可展开节点的展开图标 |
| switcherLoadingIcon | 加载状态的展开图标 |

顶层 `titleRender` 和 icon/switcherIcon 函数已迁移到对应插槽；VNode 内容 prop、数据项 title/icon/switcherIcon 函数及算法/异步回调仍保留。

```vue
<Tree :tree-data="nodes" show-icon>
  <template #title="{ node, data }">{{ data.name }}（{{ node.key }}）</template>
  <template #switcherIcon="{ node }">{{ node.expanded ? '−' : '+' }}</template>
</Tree>
```

### TreeRef（expose）

| 方法 | 说明 |
| --- | --- |
| scrollTo(number \| { key, autoExpand?, offset?, align? } \| null) | 按像素或 key 定位；align 为 top/bottom，省略时只在目标越界时滚动；autoExpand 先请求展开全部祖先 |
| focus() | 聚焦实际树容器 |
| keyEntities | 当前只读实体表，含父子关系；数字 0 与字符串 '0' 使用同一键表示，不能同时使用 |

原生 class/style 落在组件根，语义样式按区域合并；每棵树的节点 id/checkbox 标签关系由组件维护。

### DirectoryTree

`Tree.DirectoryTree` 的对应物：目录树变体（`showIcon=true` / `expandAction='click'` / `blockNode` / File-Folder 图标）；`multiple` 下支持 `shift` / `ctrl`（meta）范围多选，`select` 事件带 `selectedNodes`；完整转发 Tree 的模型、业务及原生事件，显式 false 与自定义图标有效。默认 `defaultExpandAll` 展开全部实体 key（与 Tree 的「只展开有 children」不同）。

### 主题变量

| Token | 说明 | 默认值 |
| --- | --- | --- |
| titleHeight | 节点标题高度（number，单位 px） | controlHeightSM（24px） |
| switcherSize | 展开按钮尺寸 | 24px |
| indentSize | 缩进宽度 | 24px |
| nodeHoverBg / nodeHoverColor | 节点悬浮态 | controlItemBgHover / colorText |
| nodeSelectedBg / nodeSelectedColor | 节点选中态 | controlItemBgActive / colorText |
| directoryNodeSelectedColor / directoryNodeSelectedBg | 目录树选中态 | colorTextLightSolid / colorPrimary |


## 节点占据整行 (block-node)

`blockNode` 让节点标题占据整行，选中背景覆盖整行；用 `Switch` 切换并观察选中反馈。

### block-node.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 `block-node` demo：blockNode 让节点占据整行。
import type { TreeKey } from '@apollo-design/ui';
import { Switch, Text, Tree } from '@apollo-design/ui';
import { ref } from 'vue';

const blockNode = ref(true);
const selectedKeys = ref<TreeKey[]>(['0-0-1']);

const treeData = [
  {
    title: 'parent 1',
    key: '0-0',
    children: [
      {
        title: 'parent 1-0',
        key: '0-0-0',
        children: [
          { title: 'leaf 1-0-0', key: '0-0-0-0' },
          { title: 'leaf 1-0-1', key: '0-0-0-1' },
        ],
      },
      {
        title: 'parent 1-1',
        key: '0-0-1',
        children: [
          { title: 'leaf 1-1-0', key: '0-0-1-0' },
          { title: 'leaf 1-1-1', key: '0-0-1-1' },
        ],
      },
    ],
  },
  {
    title: 'parent 2',
    key: '0-1',
    children: [
      { title: 'leaf 2-0', key: '0-1-0' },
      { title: 'leaf 2-1', key: '0-1-1' },
    ],
  },
];
</script>

<template>
  <div>
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-bottom: 12px">
      <Text>blockNode</Text>
      <Switch v-model:checked="blockNode" aria-label="整行节点" />
      <Text type="secondary">selected: {{ selectedKeys.join(', ') || '（未选中）' }}</Text>
    </div>
    <Tree
      v-model:selected-keys="selectedKeys"
      :tree-data="treeData"
      :block-node="blockNode"
      default-expand-all
      style="width: 320px; max-width: 100%"
    />
  </div>
</template>
```

## basic (basic)

最简单的用法，点击展开/收起节点，点击选择节点，勾选框勾选节点。

### basic.vue

```vue
<script setup lang="ts">
import { Tree } from '@apollo-design/ui';

const treeData = [
  {
    title: 'parent 1',
    key: '0-0',
    children: [
      {
        title: 'parent 1-0',
        key: '0-0-0',
        disabled: true,
        children: [
          { title: 'leaf', key: '0-0-0-0', disableCheckbox: true },
          { title: 'leaf', key: '0-0-0-1' },
        ],
      },
      {
        title: 'parent 1-1',
        key: '0-0-1',
        children: [{ title: 'sss', key: '0-0-1-0', style: { color: '#1677ff' } }],
      },
    ],
  },
];
</script>

<template>
  <Tree
    checkable
    :default-expanded-keys="['0-0-0', '0-0-1']"
    :default-selected-keys="['0-0-1']"
    :default-checked-keys="['0-0-0', '0-0-1']"
    :tree-data="treeData"
  />
</template>
```

## basic-controlled (basic-controlled)

受控操作示例：展开 / 勾选 / 选中全部受控。

### basic-controlled.vue

```vue
<script setup lang="ts">
import { Tree } from '@apollo-design/ui';
import { ref } from 'vue';

const treeData = [
  {
    title: '0-0',
    key: '0-0',
    children: [
      {
        title: '0-0-0',
        key: '0-0-0',
        children: [
          { title: '0-0-0-0', key: '0-0-0-0' },
          { title: '0-0-0-1', key: '0-0-0-1' },
          { title: '0-0-0-2', key: '0-0-0-2' },
        ],
      },
      {
        title: '0-0-1',
        key: '0-0-1',
        children: [
          { title: '0-0-1-0', key: '0-0-1-0' },
          { title: '0-0-1-1', key: '0-0-1-1' },
          { title: '0-0-1-2', key: '0-0-1-2' },
        ],
      },
      { title: '0-0-2', key: '0-0-2' },
    ],
  },
  {
    title: '0-1',
    key: '0-1',
    children: [
      { title: '0-1-0-0', key: '0-1-0-0' },
      { title: '0-1-0-1', key: '0-1-0-1' },
      { title: '0-1-0-2', key: '0-1-0-2' },
    ],
  },
  { title: '0-2', key: '0-2' },
];

const expandedKeys = ref<(string | number)[]>(['0-0-0', '0-0-1']);
const checkedKeys = ref<(string | number)[]>(['0-0-0']);
const selectedKeys = ref<(string | number)[]>([]);
const autoExpandParent = ref(true);

const onExpand = (keys: (string | number)[]) => {
  // rc 判据：不重置 autoExpandParent，子节点展开后父节点收不起来
  expandedKeys.value = keys;
  autoExpandParent.value = false;
};
</script>

<template>
  <Tree
    v-model:checkedKeys="checkedKeys"
    v-model:selectedKeys="selectedKeys"
    checkable
    :expanded-keys="expandedKeys"
    :auto-expand-parent="autoExpandParent"
    :tree-data="treeData"
    @expand="onExpand"
  />
</template>
```

## big-data (big-data)

大数据量下配合 `height` 开启虚拟滚动（1,022 个节点）。

### big-data.vue

```vue
<script setup lang="ts">
import { Tree } from '@apollo-design/ui';

// Two roots with nine levels produce 1,022 nodes.
interface DemoNode {
  title: string;
  key: string;
  children?: DemoNode[];
}
const build = (pre: string, level: number): DemoNode[] | undefined => {
  if (level < 0) return undefined;
  return [0, 1].map((i) => {
    const key = `${pre}${i}`;
    return { title: `节点 ${key}`, key, children: build(`${key}-`, level - 1) };
  });
};
const treeData = build('0-', 8) ?? [];
</script>

<template>
  <Tree :tree-data="treeData" :height="234" default-expand-all />
</template>
```

## component-token (component-token)

通过主题定制 Component Token（`titleHeight` / `nodeSelectedBg`）。

### component-token.vue

```vue
<script setup lang="ts">
import { Button, ConfigProvider, DirectoryTree, Tree } from '@apollo-design/ui';
import { ref } from 'vue';

const custom = ref(true);
const treeData = [
  {
    key: 'folder',
    title: '文件夹',
    children: [
      { key: 'file', title: '文件' },
      { key: 'other', title: '另一文件' },
    ],
  },
];
const tokens = {
  titleHeight: 32,
  switcherSize: 28,
  indentSize: 36,
  nodeHoverBg: '#e6fffb',
  nodeHoverColor: '#006d75',
  nodeSelectedBg: '#b5f5ec',
  nodeSelectedColor: '#00474f',
  directoryNodeSelectedBg: '#006d75',
  directoryNodeSelectedColor: '#ffffff',
};
</script>

<template>
  <Button style="margin-bottom: 16px" @click="custom = !custom">{{ custom ? '恢复默认 Token' : '使用自定义 Token' }}</Button>
  <ConfigProvider :theme="{ components: { Tree: custom ? tokens : {} } }">
    <Tree :tree-data="treeData" default-expand-all block-node :selected-keys="['file']" />
    <DirectoryTree :tree-data="treeData" default-expand-all :selected-keys="['file']" />
  </ConfigProvider>
</template>
```

## customized-icon (customized-icon)

可以自定义节点图标与展开按钮图标（`icon` / `switcherIcon`）。

### customized-icon.vue

```vue
<script setup lang="ts">
import {
  DownOutlined,
  FrownFilled,
  FrownOutlined,
  MehOutlined,
  SmileOutlined,
} from '@apollo-design/icons';
import { Tree } from '@apollo-design/ui';
import { h } from 'vue';

const treeData = [
  {
    title: 'parent 1',
    key: '0-0',
    icon: () => h(SmileOutlined),
    children: [
      { title: 'leaf', key: '0-0-0', icon: () => h(MehOutlined) },
      {
        title: 'leaf',
        key: '0-0-1',
        icon: ({ selected }: { selected?: boolean }) =>
          selected ? h(FrownFilled) : h(FrownOutlined),
      },
    ],
  },
];
</script>

<template>
  <Tree show-icon default-expand-all :default-selected-keys="['0-0-0']" :switcher-icon="h(DownOutlined)" :tree-data="treeData" />
</template>
```

## directory (directory)

内置的目录树。`multiple` 模式支持 `shift` / `ctrl`（meta）多选。

### directory.vue

```vue
<script setup lang="ts">
import { DirectoryTree } from '@apollo-design/ui';

const treeData = [
  {
    title: 'parent 0',
    key: '0-0',
    children: [
      { title: 'leaf 0-0', key: '0-0-0', isLeaf: true },
      { title: 'leaf 0-1', key: '0-0-1', isLeaf: true },
    ],
  },
  {
    title: 'parent 1',
    key: '0-1',
    children: [
      { title: 'leaf 1-0', key: '0-1-0', isLeaf: true },
      { title: 'leaf 1-1', key: '0-1-1', isLeaf: true },
    ],
  },
];
</script>

<template>
  <DirectoryTree multiple default-expand-all :tree-data="treeData" />
</template>
```

## directory-debug (directory-debug)

调试目录树的图标与选中态样式。

### directory-debug.vue

```vue
<script setup lang="ts">
import { DirectoryTree } from '@apollo-design/ui';

const treeData = [
  {
    title: 'parent 0',
    key: '0-0',
    children: [
      { title: 'leaf 0-0', key: '0-0-0', isLeaf: true },
      { title: 'leaf 0-1', key: '0-0-1', isLeaf: true },
    ],
  },
];
</script>

<template>
  <DirectoryTree :tree-data="treeData" default-expand-all />
</template>
```

## drag-debug (drag-debug)

调试拖拽指示线的专用示例。

### drag-debug.vue

```vue
<script setup lang="ts">
import { Tree } from '@apollo-design/ui';

const treeData = [
  { title: '0-0', key: '0-0', children: [{ title: '0-0-0', key: '0-0-0' }] },
  { title: '0-1', key: '0-1' },
];
</script>

<template>
  <Tree draggable :tree-data="treeData" default-expand-all />
</template>
```

## draggable (draggable)

拖动到文件夹内或节点之间。`drop(event, info)` 提供落点信息；示例更新自己的 `treeData`，并通过 `v-model:expandedKeys` 接受展开请求。

### draggable.vue

```vue
<script setup lang="ts">
import { Tree } from '@apollo-design/ui';
import { ref, shallowRef } from 'vue';
import type { DataNode, TreeDropEventInfo, TreeKey } from '../interface';

const createData = (): DataNode[] => [
  {
    key: 'a',
    title: '文件夹 A',
    children: [
      { key: 'a1', title: '文件 A1' },
      { key: 'a2', title: '文件 A2' },
    ],
  },
  { key: 'b', title: '文件夹 B', children: [{ key: 'b1', title: '文件 B1' }] },
];
const treeData = shallowRef(createData());
const expandedKeys = ref<TreeKey[]>(['a', 'b']);
const status = ref('拖动节点到文件夹内或节点之间。');

function visit(
  nodes: DataNode[],
  key: TreeKey,
  action: (node: DataNode, index: number, list: DataNode[]) => void,
): boolean {
  for (const [index, node] of nodes.entries()) {
    if (node.key === key) {
      action(node, index, nodes);
      return true;
    }
    if (node.children && visit(node.children, key, action)) return true;
  }
  return false;
}
function clone(nodes: DataNode[]): DataNode[] {
  return nodes.map((node) => ({
    ...node,
    children: node.children ? clone(node.children) : undefined,
  }));
}
function onDrop(_event: DragEvent, info: TreeDropEventInfo) {
  const next = clone(treeData.value);
  let dragged: DataNode | undefined;
  visit(next, info.dragNode.key, (node, index, list) => {
    dragged = node;
    list.splice(index, 1);
  });
  if (!dragged) return;
  const moving = dragged;
  const relativePosition = info.dropPosition - Number(info.node.pos.split('-').at(-1));
  visit(next, info.node.key, (node, index, list) => {
    if (info.dropToGap) list.splice(index + (relativePosition > 0 ? 1 : 0), 0, moving);
    else {
      node.children ??= [];
      node.children.unshift(moving);
    }
  });
  treeData.value = next;
  status.value = `已移动 ${String(moving.title)}；数据顺序已更新。`;
}
</script>

<template>
  <p role="status">{{ status }}</p>
  <Tree v-model:expanded-keys="expandedKeys" draggable block-node :tree-data="treeData" @drop="onDrop" />
</template>
```

### ../interface.ts

```ts
import type { CSSProperties, VNodeChild } from 'vue';
import type {
  BasicDataNode,
  DataNode,
  EventDataNode,
  SafeKey,
  TreeDataEntity,
  TreeDraggable,
  TreeExpandAction,
  TreeFieldNames,
  TreeIconType,
  TreeKey,
} from '../_internal/tree/types';

// ── 数据模型的定义已搬到 packages/ui/src/_internal/tree/types.ts ──────────────
//
// 裁决 `early-extract-table-core-tree-core` = **C**（2026-10-07）：`tree` 的纯逻辑
// （键实体表 / 勾选传导 / 数组增删）有 ≥2 个消费者（`tree-select` / `table`），
// 按「共享工具必须放 `src/_internal/`」该搬出组件目录；而那些逻辑**依赖这份数据模型**
// ⇒ 只搬函数会造成 `_internal/ → tree/` 的反向依赖，比原状更糟。所以类型跟着一起搬。
//
// ⚠️ 下面这一句**不能删**：它保证公开 API 面与所有既有的 `tree/interface` 导入站点
//    完全不变（`FieldDataNode` / `TreeNodeRenderInfo` / `TreeNodeDraggableFn` /
//    `TreeDraggableConfig` 本文件已不再直接使用，但仍是对外契约的一部分）。
export type {
  BasicDataNode,
  DataNode,
  EventDataNode,
  FieldDataNode,
  SafeKey,
  TreeDataEntity,
  TreeDraggable,
  TreeDraggableConfig,
  TreeExpandAction,
  TreeFieldNames,
  TreeIconType,
  TreeKey,
  TreeNodeDraggableFn,
  TreeNodeRenderInfo,
} from '../_internal/tree/types';

/** rc `AllowDrop`。 */
export interface TreeAllowDropOptions<TreeDataType extends BasicDataNode = DataNode> {
  dragNode: TreeDataType;
  dropNode: TreeDataType;
  dropPosition: -1 | 0 | 1;
}
export type TreeAllowDrop<TreeDataType extends BasicDataNode = DataNode> = (
  options: TreeAllowDropOptions<TreeDataType>,
) => boolean;

// ---------------------------------------------------------------------------
// 事件信息（rc 逐字段）
// ---------------------------------------------------------------------------

export interface TreeExpandEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  node: EventDataNode<TreeDataType>;
  expanded: boolean;
  nativeEvent: MouseEvent | KeyboardEvent;
}

export interface TreeCheckInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'check';
  node: EventDataNode<TreeDataType>;
  checked: boolean;
  nativeEvent: MouseEvent | KeyboardEvent;
  checkedNodes: TreeDataType[];
  /** 仅非 checkStrictly（级联）时携带（rc [Legacy]，tree-select 依赖）。 */
  checkedNodesPositions?: { node: TreeDataType; pos: string }[];
  halfCheckedKeys?: SafeKey[];
}

export interface TreeSelectEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'select';
  selected: boolean;
  node: EventDataNode<TreeDataType>;
  selectedNodes: TreeDataType[];
  nativeEvent: MouseEvent | KeyboardEvent;
}

export interface TreeLoadEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'load';
  node: EventDataNode<TreeDataType>;
}

export interface TreeDragEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  node: EventDataNode<TreeDataType>;
}

export interface TreeDragEnterEventInfo<TreeDataType extends BasicDataNode = DataNode>
  extends TreeDragEventInfo<TreeDataType> {
  expandedKeys: TreeKey[];
}

export interface TreeDropEventInfo<TreeDataType extends BasicDataNode = DataNode>
  extends TreeDragEventInfo<TreeDataType> {
  dragNode: EventDataNode<TreeDataType>;
  dragNodesKeys: TreeKey[];
  dropPosition: number;
  dropToGap: boolean;
}

// ---------------------------------------------------------------------------
// 语义化槽位（5 个；antd `TreeSemanticType`）
// ---------------------------------------------------------------------------

export interface TreeSemanticClassNames {
  root?: string;
  item?: string;
  itemIcon?: string;
  itemTitle?: string;
  itemSwitcher?: string;
}

export interface TreeSemanticStyles {
  root?: CSSProperties;
  item?: CSSProperties;
  itemIcon?: CSSProperties;
  itemTitle?: CSSProperties;
  itemSwitcher?: CSSProperties;
}

/** 函数形态（裁决 `empty-semantic-fn` = B）。 */
export type TreeSemanticValue<T> = T | ((info: { props: TreeProps }) => T);

// ---------------------------------------------------------------------------
// Props（antd 面 = Omit<rc TreeProps, ...> + antd 追加）
// ---------------------------------------------------------------------------

/** rc `checkedKeys` 的对象形态。 */
export interface TreeCheckedKeys {
  checked: SafeKey[];
  halfChecked: SafeKey[];
}

/**
 * `scrollTo` 的参数（rc 的 `ScrollTo` 配置：数字 / `{ key, autoExpand? }` / 对齐配置）。
 *
 * 🚨 **字段名是 `align`，不是 DOM `scrollIntoView` 的 `block` / `inline`**（2026-09-30 修）：
 *    原来这里写了 `block` / `inline`，但
 *      ①文档 `index.zh-CN.md` 的方法表写的是 `scrollTo({ key, autoExpand?, offset?, align? })`；
 *      ②实现（`Tree.ts` → `NodeList.ts`）把配置**原样透传**给 `@apollo-design/virtual-list`，
 *        而它的 `ScrollAlign = 'top' | 'bottom'`（对拍 rc-virtual-list）；
 *    三方只有本接口不一致 ⇒ 调用方按文档写 `align: 'top'` 会被类型系统拒绝
 *    （demo `scroll-to.vue` 就是这样暴露出来的），按接口写 `block` 则**静默失效**。
 *
 * ⚠️ 值域只到 `'top' | 'bottom'`（本仓 virtual-list 的 `ScrollAlign`），没有 `'auto'`。
 */
export interface TreeScrollConfig {
  key: TreeKey;
  autoExpand?: boolean;
  /** 距视口顶部的附加偏移（rc `itemScrollOffset`）。 */
  offset?: number;
  /** 对齐方式：贴顶 / 贴底。缺省时不滚动（见 virtual-list 的 scroll-target 契约）。 */
  align?: 'top' | 'bottom';
}

export interface TreeProps<TreeDataType extends object = object> {
  // ---- 数据 ----
  /** 树数据（v6 主通道；`<TreeNode>` children 形态已 deprecated，不实现）。 */
  treeData?: TreeDataType[];
  /** 字段名映射（title / key / children）。 */
  fieldNames?: TreeFieldNames;

  // ---- 展开态 ----
  expandedKeys?: TreeKey[];
  defaultExpandedKeys?: TreeKey[];
  /** 默认展开全部（**只展开有 children 的节点** —— rc gDSFP 判据）。 */
  defaultExpandAll?: boolean;
  /** 默认展开父节点（受控 expandedKeys 首挂时也 conductExpandParent 补全祖先）。 */
  defaultExpandParent?: boolean;
  /** 展开受控时自动补全祖先（autoExpandParent）。 */
  autoExpandParent?: boolean;

  // ---- 勾选态 ----
  checkable?: boolean | VNodeChild;
  checkStrictly?: boolean;
  checkedKeys?: SafeKey[] | TreeCheckedKeys;
  defaultCheckedKeys?: SafeKey[];

  // ---- 选中态 ----
  selectable?: boolean;
  multiple?: boolean;
  selectedKeys?: TreeKey[];
  defaultSelectedKeys?: TreeKey[];

  // ---- 异步加载 ----
  loadData?: (node: EventDataNode) => Promise<unknown>;
  loadedKeys?: SafeKey[];

  // ---- 外观 ----
  showIcon?: boolean;
  showLine?: boolean | { showLeafIcon: boolean | TreeIconType };
  icon?: VNodeChild;
  switcherIcon?: VNodeChild;
  switcherLoadingIcon?: VNodeChild;
  blockNode?: boolean;
  /** 点击/双击节点时是否触发展开（DirectoryTree 默认 'click'）。 */
  expandAction?: TreeExpandAction;

  // ---- 禁用 / 拖拽 ----
  disabled?: boolean;
  draggable?: TreeDraggable;
  allowDrop?: TreeAllowDrop;

  // ---- 滚动 / 虚拟 ----
  /** 虚拟滚动容器高度（不传则不虚拟）。 */
  height?: number;
  /** 行高（antd 用 `paddingXS/2 + titleHeight` 计算，勿手传）。 */
  itemHeight?: number;
  scrollWidth?: number;
  virtual?: boolean;
  /** activeKey 滚动跟随时的附加偏移。 */
  itemScrollOffset?: number;

  // ---- 焦点 / ARIA ----
  focusable?: boolean;
  activeKey?: TreeKey | null;
  tabIndex?: number;
  /** rc 自述「TODO: full a11y」—— 现状键盘可达 + active 跟随；无 tree role（UPSTREAM）。 */

  // ---- 过滤 ----
  filterTreeNode?: (node: EventDataNode) => boolean;

  // ---- 常规 ----
  prefixCls?: string;
  /** @deprecated 请用 `styles.root`（antd v6 标记）。 */
  rootStyle?: CSSProperties;
  classNames?: TreeSemanticValue<TreeSemanticClassNames>;
  styles?: TreeSemanticValue<TreeSemanticStyles>;
}

// ---------------------------------------------------------------------------
// Emits（C11：v-model 与语义事件同发）
// ---------------------------------------------------------------------------

export interface TreeEmits {
  /** `v-model:expandedKeys`。 */
  (e: 'update:expandedKeys', keys: TreeKey[]): void;
  /** `v-model:checkedKeys`；checkStrictly 时为对象形态。 */
  (e: 'update:checkedKeys', keys: SafeKey[] | TreeCheckedKeys): void;
  /** `v-model:selectedKeys`。 */
  (e: 'update:selectedKeys', keys: TreeKey[]): void;
  /** `v-model:loadedKeys`。 */
  (e: 'update:loadedKeys', keys: SafeKey[]): void;
  (e: 'update:activeKey', key: TreeKey | null): void;
  (e: 'activeChange', key: TreeKey | null): void;
  /** 展开/收起（与 `update:expandedKeys` 同发）。 */
  (e: 'expand', keys: TreeKey[], info: TreeExpandEventInfo): void;
  /** 勾选（与 `update:checkedKeys` 同发；返回值形态随 checkStrictly）。 */
  (e: 'check', checked: SafeKey[] | TreeCheckedKeys, info: TreeCheckInfo): void;
  /** 选中（与 `update:selectedKeys` 同发）。 */
  (e: 'select', keys: TreeKey[], info: TreeSelectEventInfo): void;
  /** 异步加载完成（与 `update:loadedKeys` 同发）。 */
  (e: 'load', keys: SafeKey[], info: TreeLoadEventInfo): void;
  (e: 'click', evt: MouseEvent, node: EventDataNode): void;
  (e: 'doubleClick', evt: MouseEvent, node: EventDataNode): void;
  (e: 'contextmenu', evt: MouseEvent, node: EventDataNode): void;
  (e: 'mouseEnter', evt: MouseEvent, node: EventDataNode): void;
  (e: 'mouseLeave', evt: MouseEvent, node: EventDataNode): void;
  (e: 'dragStart', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragEnter', evt: DragEvent, info: TreeDragEnterEventInfo): void;
  (e: 'dragOver', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragLeave', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragEnd', evt: DragEvent, info: { node: EventDataNode | null }): void;
  (e: 'drop', evt: DragEvent, info: TreeDropEventInfo): void;
}

// ---------------------------------------------------------------------------
// Slots
// ---------------------------------------------------------------------------

export interface TreeSlotScope<TreeDataType extends object = Record<string, unknown>> {
  node: EventDataNode;
  data: TreeDataType;
}

export interface TreeSlots<TreeDataType extends object = Record<string, unknown>> {
  /** Slot presence takes priority, including an intentionally empty result. */
  title?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  icon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  switcherIcon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  switcherLoadingIcon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
}

// ---------------------------------------------------------------------------
// Expose（rc class 实例的公开方法面）
// ---------------------------------------------------------------------------

export interface TreeRef<TreeDataType extends object = DataNode> {
  /** 滚动到指定节点；`autoExpand: true` 时先展开再滚。 */
  scrollTo: (scroll?: number | TreeScrollConfig | null) => void;
  /** 聚焦树容器（rc focusable 管理）。 */
  focus: () => void;
  /** 节点数据实体表（只读快照）。 */
  keyEntities: Record<SafeKey, TreeDataEntity<TreeDataType>>;
}

// ---------------------------------------------------------------------------
// DirectoryTree
// ---------------------------------------------------------------------------

/**
 * DirectoryTree 的 props：与 TreeProps 相同，但**默认值不同**（G1 §4）——
 * `showIcon=true` / `expandAction='click'` / `blockNode=true` / `defaultExpandParent=true`
 * + shift/ctrl 范围多选 + File/Folder 图标。类型上直接复用 {@link TreeProps}。
 */
export type DirectoryTreeProps = TreeProps;
```

### ../../_internal/tree/types.ts

```ts
/**
 * Tree 数据模型的**共享类型**。
 *
 * ── 为什么这份类型不在 `packages/ui/src/tree/interface.ts` 里 ──────────────────
 *
 * 裁决 `early-extract-table-core-tree-core` = **C**（2026-10-07 用户裁决）：
 * `tree` 的纯逻辑（键实体表 / 勾选传导 / 数组增删）有 **≥2 个消费者**
 * （`tree-select` 与 `table`），按本仓「共享工具必须放 `src/_internal/`」的准则
 * 该搬出组件目录。
 *
 * 但那些逻辑**依赖这份数据模型** —— 只搬函数、把类型留在 `tree/interface.ts`，
 * 就会造出 `_internal/ → tree/` 的**反向依赖**，比原来的「组件间互 import」更糟。
 * ⇒ 所以**类型跟着逻辑一起搬**。
 *
 * `tree/interface.ts` 会把它们原样再导出
 * （`export type { … } from '../_internal/tree/types'`）
 * ⇒ 公开 API 面与所有既有的 `tree/interface` 导入站点**都不受影响**。
 *
 * 契约来源：antd 6.6.4 `es/tree/Tree.d.ts` + `@rc-component/tree` 1.4.0 的
 * `Tree.d.ts` / `interface.d.ts`。分析见 `docs/analysis/tree.md`。
 *
 * ⚠️ 禁止 any / as any / @ts-expect-error（H10）。
 */

import type { CSSProperties, VNodeChild } from 'vue';

/** `React.Key` 的 Vue 对应物；`SafeKey` 排除 bigint（rc :88-95 的既有约束）。 */
export type TreeKey = string | number;
export type SafeKey = Exclude<TreeKey, bigint>;

/** rc `FieldDataNode`：用户数据节点 + 递归 children（字段名可由 fieldNames 改写）。 */
export interface BasicDataNode {
  checkable?: boolean;
  disabled?: boolean;
  disableCheckbox?: boolean;
  icon?: TreeIconType;
  isLeaf?: boolean;
  selectable?: boolean;
  switcherIcon?: TreeIconType;
  className?: string;
  style?: CSSProperties;
}

export type FieldDataNode<T, ChildFieldName extends string = 'children'> = BasicDataNode &
  T &
  Partial<Record<ChildFieldName, FieldDataNode<T, ChildFieldName>[]>>;

/** rc `DataNode`（默认字段名形态）。 */
export type DataNode = FieldDataNode<{
  key: TreeKey;
  title?: VNodeChild | ((data: DataNode) => VNodeChild);
}>;

/** rc `EventDataNode`：事件回调里的节点（数据 + 运行时态）。 */
export type EventDataNode<TreeDataType extends BasicDataNode = DataNode> = {
  key: TreeKey;
  expanded: boolean;
  selected: boolean;
  checked: boolean;
  loaded: boolean;
  loading: boolean;
  halfChecked: boolean;
  dragOver: boolean;
  dragOverGapTop: boolean;
  dragOverGapBottom: boolean;
  pos: string;
  active: boolean;
} & TreeDataType &
  BasicDataNode;

/** rc `FieldNames`（`_title` 仅 tree-select 内部使用，保留字段不公开）。 */
export interface TreeFieldNames {
  title?: string;
  key?: string;
  children?: string;
}

/** rc `DataEntity`（键实体表值；keyEntities 的公开形态）。 */
export interface TreeDataEntity<TreeDataType extends object = DataNode> {
  index: number;
  key: SafeKey;
  pos: string;
  level: number;
  node: TreeDataType;
  nodes: TreeDataType[];
  children?: TreeDataEntity<TreeDataType>[];
  parent?: TreeDataEntity<TreeDataType>;
}

/** 节点态传给 icon/switcherIcon fn 的参数（rc `TreeNodeProps` 的只读子集）。 */
export interface TreeNodeRenderInfo<TreeDataType extends object = Record<string, unknown>> {
  eventKey?: TreeKey;
  expanded?: boolean;
  selected?: boolean;
  checked?: boolean;
  loaded?: boolean;
  loading?: boolean;
  halfChecked?: boolean;
  dragOver?: boolean;
  dragOverGapTop?: boolean;
  dragOverGapBottom?: boolean;
  pos?: string;
  data?: TreeDataType;
  isLeaf?: boolean;
  checkable?: boolean;
  selectable?: boolean;
  disabled?: boolean;
  disableCheckbox?: boolean;
  /** 展开函数等注入位与 rc 的 treeNodeProps 同构。 */
  [key: string]: unknown;
}

/** rc `IconType`：VNode 或按节点态求值的 fn。 */
export type TreeIconType<TreeDataType extends object = Record<string, unknown>> =
  | VNodeChild
  | ((props: TreeNodeRenderInfo<TreeDataType>) => VNodeChild);

/** rc `ExpandAction`。 */
export type TreeExpandAction = false | 'click' | 'doubleClick';

/** rc `DraggableFn` / `DraggableConfig`。 */
export type TreeNodeDraggableFn = (node: DataNode) => boolean;
export interface TreeDraggableConfig {
  /** `false` 显式关闭拖拽把手（默认渲染 HolderOutlined）。 */
  icon?: VNodeChild | false;
  nodeDraggable?: TreeNodeDraggableFn;
}
export type TreeDraggable = TreeNodeDraggableFn | boolean | TreeDraggableConfig;
```

## dynamic (dynamic)

点击展开节点时异步加载数据（`loadData`）。

### dynamic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 dynamic demo。
// ⚠️ 两处类型要点：①`treeData` 用公开的 `DataNode`（别推断成 `unknown[]`）；
//    ②`loadData` 的签名是 `(node: EventDataNode) => Promise<unknown>`。
import { Tree } from '@apollo-design/ui';
import { ref, shallowRef } from 'vue';
// ⚠️ `DataNode` / `EventDataNode` **不在包根导出**（根 barrel 只导 `Tree*` 前缀的类型）
//    ⇒ 从组件的本地模块导入；写成 `from '@apollo-design/ui'` 会报 TS2305。
import type { DataNode, EventDataNode } from '../interface';

const initTreeData: DataNode[] = [
  { title: 'Expand to load', key: '0' },
  { title: 'Expand to load', key: '1' },
  { title: 'Tree Node', key: '2', isLeaf: true },
];

const treeData = shallowRef<DataNode[]>(initTreeData);

function updateTreeData(list: DataNode[], key: string | number, children: DataNode[]): DataNode[] {
  return list.map((node) => {
    if (node.key === key) return { ...node, children };
    if (node.children) return { ...node, children: updateTreeData(node.children, key, children) };
    return node;
  });
}

const onLoadData = (treeNode: EventDataNode): Promise<unknown> =>
  new Promise<void>((resolve) => {
    if (treeNode.children) {
      resolve();
      return;
    }
    setTimeout(() => {
      treeData.value = updateTreeData(treeData.value, String(treeNode.key), [
        { title: 'Child Node', key: `${String(treeNode.key)}-0` },
        { title: 'Child Node', key: `${String(treeNode.key)}-1` },
      ]);
      resolve();
    }, 1000);
  });
</script>

<template>
  <Tree :load-data="onLoadData" :tree-data="treeData" />
</template>
```

### ../interface.ts

```ts
import type { CSSProperties, VNodeChild } from 'vue';
import type {
  BasicDataNode,
  DataNode,
  EventDataNode,
  SafeKey,
  TreeDataEntity,
  TreeDraggable,
  TreeExpandAction,
  TreeFieldNames,
  TreeIconType,
  TreeKey,
} from '../_internal/tree/types';

// ── 数据模型的定义已搬到 packages/ui/src/_internal/tree/types.ts ──────────────
//
// 裁决 `early-extract-table-core-tree-core` = **C**（2026-10-07）：`tree` 的纯逻辑
// （键实体表 / 勾选传导 / 数组增删）有 ≥2 个消费者（`tree-select` / `table`），
// 按「共享工具必须放 `src/_internal/`」该搬出组件目录；而那些逻辑**依赖这份数据模型**
// ⇒ 只搬函数会造成 `_internal/ → tree/` 的反向依赖，比原状更糟。所以类型跟着一起搬。
//
// ⚠️ 下面这一句**不能删**：它保证公开 API 面与所有既有的 `tree/interface` 导入站点
//    完全不变（`FieldDataNode` / `TreeNodeRenderInfo` / `TreeNodeDraggableFn` /
//    `TreeDraggableConfig` 本文件已不再直接使用，但仍是对外契约的一部分）。
export type {
  BasicDataNode,
  DataNode,
  EventDataNode,
  FieldDataNode,
  SafeKey,
  TreeDataEntity,
  TreeDraggable,
  TreeDraggableConfig,
  TreeExpandAction,
  TreeFieldNames,
  TreeIconType,
  TreeKey,
  TreeNodeDraggableFn,
  TreeNodeRenderInfo,
} from '../_internal/tree/types';

/** rc `AllowDrop`。 */
export interface TreeAllowDropOptions<TreeDataType extends BasicDataNode = DataNode> {
  dragNode: TreeDataType;
  dropNode: TreeDataType;
  dropPosition: -1 | 0 | 1;
}
export type TreeAllowDrop<TreeDataType extends BasicDataNode = DataNode> = (
  options: TreeAllowDropOptions<TreeDataType>,
) => boolean;

// ---------------------------------------------------------------------------
// 事件信息（rc 逐字段）
// ---------------------------------------------------------------------------

export interface TreeExpandEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  node: EventDataNode<TreeDataType>;
  expanded: boolean;
  nativeEvent: MouseEvent | KeyboardEvent;
}

export interface TreeCheckInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'check';
  node: EventDataNode<TreeDataType>;
  checked: boolean;
  nativeEvent: MouseEvent | KeyboardEvent;
  checkedNodes: TreeDataType[];
  /** 仅非 checkStrictly（级联）时携带（rc [Legacy]，tree-select 依赖）。 */
  checkedNodesPositions?: { node: TreeDataType; pos: string }[];
  halfCheckedKeys?: SafeKey[];
}

export interface TreeSelectEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'select';
  selected: boolean;
  node: EventDataNode<TreeDataType>;
  selectedNodes: TreeDataType[];
  nativeEvent: MouseEvent | KeyboardEvent;
}

export interface TreeLoadEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'load';
  node: EventDataNode<TreeDataType>;
}

export interface TreeDragEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  node: EventDataNode<TreeDataType>;
}

export interface TreeDragEnterEventInfo<TreeDataType extends BasicDataNode = DataNode>
  extends TreeDragEventInfo<TreeDataType> {
  expandedKeys: TreeKey[];
}

export interface TreeDropEventInfo<TreeDataType extends BasicDataNode = DataNode>
  extends TreeDragEventInfo<TreeDataType> {
  dragNode: EventDataNode<TreeDataType>;
  dragNodesKeys: TreeKey[];
  dropPosition: number;
  dropToGap: boolean;
}

// ---------------------------------------------------------------------------
// 语义化槽位（5 个；antd `TreeSemanticType`）
// ---------------------------------------------------------------------------

export interface TreeSemanticClassNames {
  root?: string;
  item?: string;
  itemIcon?: string;
  itemTitle?: string;
  itemSwitcher?: string;
}

export interface TreeSemanticStyles {
  root?: CSSProperties;
  item?: CSSProperties;
  itemIcon?: CSSProperties;
  itemTitle?: CSSProperties;
  itemSwitcher?: CSSProperties;
}

/** 函数形态（裁决 `empty-semantic-fn` = B）。 */
export type TreeSemanticValue<T> = T | ((info: { props: TreeProps }) => T);

// ---------------------------------------------------------------------------
// Props（antd 面 = Omit<rc TreeProps, ...> + antd 追加）
// ---------------------------------------------------------------------------

/** rc `checkedKeys` 的对象形态。 */
export interface TreeCheckedKeys {
  checked: SafeKey[];
  halfChecked: SafeKey[];
}

/**
 * `scrollTo` 的参数（rc 的 `ScrollTo` 配置：数字 / `{ key, autoExpand? }` / 对齐配置）。
 *
 * 🚨 **字段名是 `align`，不是 DOM `scrollIntoView` 的 `block` / `inline`**（2026-09-30 修）：
 *    原来这里写了 `block` / `inline`，但
 *      ①文档 `index.zh-CN.md` 的方法表写的是 `scrollTo({ key, autoExpand?, offset?, align? })`；
 *      ②实现（`Tree.ts` → `NodeList.ts`）把配置**原样透传**给 `@apollo-design/virtual-list`，
 *        而它的 `ScrollAlign = 'top' | 'bottom'`（对拍 rc-virtual-list）；
 *    三方只有本接口不一致 ⇒ 调用方按文档写 `align: 'top'` 会被类型系统拒绝
 *    （demo `scroll-to.vue` 就是这样暴露出来的），按接口写 `block` 则**静默失效**。
 *
 * ⚠️ 值域只到 `'top' | 'bottom'`（本仓 virtual-list 的 `ScrollAlign`），没有 `'auto'`。
 */
export interface TreeScrollConfig {
  key: TreeKey;
  autoExpand?: boolean;
  /** 距视口顶部的附加偏移（rc `itemScrollOffset`）。 */
  offset?: number;
  /** 对齐方式：贴顶 / 贴底。缺省时不滚动（见 virtual-list 的 scroll-target 契约）。 */
  align?: 'top' | 'bottom';
}

export interface TreeProps<TreeDataType extends object = object> {
  // ---- 数据 ----
  /** 树数据（v6 主通道；`<TreeNode>` children 形态已 deprecated，不实现）。 */
  treeData?: TreeDataType[];
  /** 字段名映射（title / key / children）。 */
  fieldNames?: TreeFieldNames;

  // ---- 展开态 ----
  expandedKeys?: TreeKey[];
  defaultExpandedKeys?: TreeKey[];
  /** 默认展开全部（**只展开有 children 的节点** —— rc gDSFP 判据）。 */
  defaultExpandAll?: boolean;
  /** 默认展开父节点（受控 expandedKeys 首挂时也 conductExpandParent 补全祖先）。 */
  defaultExpandParent?: boolean;
  /** 展开受控时自动补全祖先（autoExpandParent）。 */
  autoExpandParent?: boolean;

  // ---- 勾选态 ----
  checkable?: boolean | VNodeChild;
  checkStrictly?: boolean;
  checkedKeys?: SafeKey[] | TreeCheckedKeys;
  defaultCheckedKeys?: SafeKey[];

  // ---- 选中态 ----
  selectable?: boolean;
  multiple?: boolean;
  selectedKeys?: TreeKey[];
  defaultSelectedKeys?: TreeKey[];

  // ---- 异步加载 ----
  loadData?: (node: EventDataNode) => Promise<unknown>;
  loadedKeys?: SafeKey[];

  // ---- 外观 ----
  showIcon?: boolean;
  showLine?: boolean | { showLeafIcon: boolean | TreeIconType };
  icon?: VNodeChild;
  switcherIcon?: VNodeChild;
  switcherLoadingIcon?: VNodeChild;
  blockNode?: boolean;
  /** 点击/双击节点时是否触发展开（DirectoryTree 默认 'click'）。 */
  expandAction?: TreeExpandAction;

  // ---- 禁用 / 拖拽 ----
  disabled?: boolean;
  draggable?: TreeDraggable;
  allowDrop?: TreeAllowDrop;

  // ---- 滚动 / 虚拟 ----
  /** 虚拟滚动容器高度（不传则不虚拟）。 */
  height?: number;
  /** 行高（antd 用 `paddingXS/2 + titleHeight` 计算，勿手传）。 */
  itemHeight?: number;
  scrollWidth?: number;
  virtual?: boolean;
  /** activeKey 滚动跟随时的附加偏移。 */
  itemScrollOffset?: number;

  // ---- 焦点 / ARIA ----
  focusable?: boolean;
  activeKey?: TreeKey | null;
  tabIndex?: number;
  /** rc 自述「TODO: full a11y」—— 现状键盘可达 + active 跟随；无 tree role（UPSTREAM）。 */

  // ---- 过滤 ----
  filterTreeNode?: (node: EventDataNode) => boolean;

  // ---- 常规 ----
  prefixCls?: string;
  /** @deprecated 请用 `styles.root`（antd v6 标记）。 */
  rootStyle?: CSSProperties;
  classNames?: TreeSemanticValue<TreeSemanticClassNames>;
  styles?: TreeSemanticValue<TreeSemanticStyles>;
}

// ---------------------------------------------------------------------------
// Emits（C11：v-model 与语义事件同发）
// ---------------------------------------------------------------------------

export interface TreeEmits {
  /** `v-model:expandedKeys`。 */
  (e: 'update:expandedKeys', keys: TreeKey[]): void;
  /** `v-model:checkedKeys`；checkStrictly 时为对象形态。 */
  (e: 'update:checkedKeys', keys: SafeKey[] | TreeCheckedKeys): void;
  /** `v-model:selectedKeys`。 */
  (e: 'update:selectedKeys', keys: TreeKey[]): void;
  /** `v-model:loadedKeys`。 */
  (e: 'update:loadedKeys', keys: SafeKey[]): void;
  (e: 'update:activeKey', key: TreeKey | null): void;
  (e: 'activeChange', key: TreeKey | null): void;
  /** 展开/收起（与 `update:expandedKeys` 同发）。 */
  (e: 'expand', keys: TreeKey[], info: TreeExpandEventInfo): void;
  /** 勾选（与 `update:checkedKeys` 同发；返回值形态随 checkStrictly）。 */
  (e: 'check', checked: SafeKey[] | TreeCheckedKeys, info: TreeCheckInfo): void;
  /** 选中（与 `update:selectedKeys` 同发）。 */
  (e: 'select', keys: TreeKey[], info: TreeSelectEventInfo): void;
  /** 异步加载完成（与 `update:loadedKeys` 同发）。 */
  (e: 'load', keys: SafeKey[], info: TreeLoadEventInfo): void;
  (e: 'click', evt: MouseEvent, node: EventDataNode): void;
  (e: 'doubleClick', evt: MouseEvent, node: EventDataNode): void;
  (e: 'contextmenu', evt: MouseEvent, node: EventDataNode): void;
  (e: 'mouseEnter', evt: MouseEvent, node: EventDataNode): void;
  (e: 'mouseLeave', evt: MouseEvent, node: EventDataNode): void;
  (e: 'dragStart', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragEnter', evt: DragEvent, info: TreeDragEnterEventInfo): void;
  (e: 'dragOver', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragLeave', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragEnd', evt: DragEvent, info: { node: EventDataNode | null }): void;
  (e: 'drop', evt: DragEvent, info: TreeDropEventInfo): void;
}

// ---------------------------------------------------------------------------
// Slots
// ---------------------------------------------------------------------------

export interface TreeSlotScope<TreeDataType extends object = Record<string, unknown>> {
  node: EventDataNode;
  data: TreeDataType;
}

export interface TreeSlots<TreeDataType extends object = Record<string, unknown>> {
  /** Slot presence takes priority, including an intentionally empty result. */
  title?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  icon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  switcherIcon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  switcherLoadingIcon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
}

// ---------------------------------------------------------------------------
// Expose（rc class 实例的公开方法面）
// ---------------------------------------------------------------------------

export interface TreeRef<TreeDataType extends object = DataNode> {
  /** 滚动到指定节点；`autoExpand: true` 时先展开再滚。 */
  scrollTo: (scroll?: number | TreeScrollConfig | null) => void;
  /** 聚焦树容器（rc focusable 管理）。 */
  focus: () => void;
  /** 节点数据实体表（只读快照）。 */
  keyEntities: Record<SafeKey, TreeDataEntity<TreeDataType>>;
}

// ---------------------------------------------------------------------------
// DirectoryTree
// ---------------------------------------------------------------------------

/**
 * DirectoryTree 的 props：与 TreeProps 相同，但**默认值不同**（G1 §4）——
 * `showIcon=true` / `expandAction='click'` / `blockNode=true` / `defaultExpandParent=true`
 * + shift/ctrl 范围多选 + File/Folder 图标。类型上直接复用 {@link TreeProps}。
 */
export type DirectoryTreeProps = TreeProps;
```

### ../../_internal/tree/types.ts

```ts
/**
 * Tree 数据模型的**共享类型**。
 *
 * ── 为什么这份类型不在 `packages/ui/src/tree/interface.ts` 里 ──────────────────
 *
 * 裁决 `early-extract-table-core-tree-core` = **C**（2026-10-07 用户裁决）：
 * `tree` 的纯逻辑（键实体表 / 勾选传导 / 数组增删）有 **≥2 个消费者**
 * （`tree-select` 与 `table`），按本仓「共享工具必须放 `src/_internal/`」的准则
 * 该搬出组件目录。
 *
 * 但那些逻辑**依赖这份数据模型** —— 只搬函数、把类型留在 `tree/interface.ts`，
 * 就会造出 `_internal/ → tree/` 的**反向依赖**，比原来的「组件间互 import」更糟。
 * ⇒ 所以**类型跟着逻辑一起搬**。
 *
 * `tree/interface.ts` 会把它们原样再导出
 * （`export type { … } from '../_internal/tree/types'`）
 * ⇒ 公开 API 面与所有既有的 `tree/interface` 导入站点**都不受影响**。
 *
 * 契约来源：antd 6.6.4 `es/tree/Tree.d.ts` + `@rc-component/tree` 1.4.0 的
 * `Tree.d.ts` / `interface.d.ts`。分析见 `docs/analysis/tree.md`。
 *
 * ⚠️ 禁止 any / as any / @ts-expect-error（H10）。
 */

import type { CSSProperties, VNodeChild } from 'vue';

/** `React.Key` 的 Vue 对应物；`SafeKey` 排除 bigint（rc :88-95 的既有约束）。 */
export type TreeKey = string | number;
export type SafeKey = Exclude<TreeKey, bigint>;

/** rc `FieldDataNode`：用户数据节点 + 递归 children（字段名可由 fieldNames 改写）。 */
export interface BasicDataNode {
  checkable?: boolean;
  disabled?: boolean;
  disableCheckbox?: boolean;
  icon?: TreeIconType;
  isLeaf?: boolean;
  selectable?: boolean;
  switcherIcon?: TreeIconType;
  className?: string;
  style?: CSSProperties;
}

export type FieldDataNode<T, ChildFieldName extends string = 'children'> = BasicDataNode &
  T &
  Partial<Record<ChildFieldName, FieldDataNode<T, ChildFieldName>[]>>;

/** rc `DataNode`（默认字段名形态）。 */
export type DataNode = FieldDataNode<{
  key: TreeKey;
  title?: VNodeChild | ((data: DataNode) => VNodeChild);
}>;

/** rc `EventDataNode`：事件回调里的节点（数据 + 运行时态）。 */
export type EventDataNode<TreeDataType extends BasicDataNode = DataNode> = {
  key: TreeKey;
  expanded: boolean;
  selected: boolean;
  checked: boolean;
  loaded: boolean;
  loading: boolean;
  halfChecked: boolean;
  dragOver: boolean;
  dragOverGapTop: boolean;
  dragOverGapBottom: boolean;
  pos: string;
  active: boolean;
} & TreeDataType &
  BasicDataNode;

/** rc `FieldNames`（`_title` 仅 tree-select 内部使用，保留字段不公开）。 */
export interface TreeFieldNames {
  title?: string;
  key?: string;
  children?: string;
}

/** rc `DataEntity`（键实体表值；keyEntities 的公开形态）。 */
export interface TreeDataEntity<TreeDataType extends object = DataNode> {
  index: number;
  key: SafeKey;
  pos: string;
  level: number;
  node: TreeDataType;
  nodes: TreeDataType[];
  children?: TreeDataEntity<TreeDataType>[];
  parent?: TreeDataEntity<TreeDataType>;
}

/** 节点态传给 icon/switcherIcon fn 的参数（rc `TreeNodeProps` 的只读子集）。 */
export interface TreeNodeRenderInfo<TreeDataType extends object = Record<string, unknown>> {
  eventKey?: TreeKey;
  expanded?: boolean;
  selected?: boolean;
  checked?: boolean;
  loaded?: boolean;
  loading?: boolean;
  halfChecked?: boolean;
  dragOver?: boolean;
  dragOverGapTop?: boolean;
  dragOverGapBottom?: boolean;
  pos?: string;
  data?: TreeDataType;
  isLeaf?: boolean;
  checkable?: boolean;
  selectable?: boolean;
  disabled?: boolean;
  disableCheckbox?: boolean;
  /** 展开函数等注入位与 rc 的 treeNodeProps 同构。 */
  [key: string]: unknown;
}

/** rc `IconType`：VNode 或按节点态求值的 fn。 */
export type TreeIconType<TreeDataType extends object = Record<string, unknown>> =
  | VNodeChild
  | ((props: TreeNodeRenderInfo<TreeDataType>) => VNodeChild);

/** rc `ExpandAction`。 */
export type TreeExpandAction = false | 'click' | 'doubleClick';

/** rc `DraggableFn` / `DraggableConfig`。 */
export type TreeNodeDraggableFn = (node: DataNode) => boolean;
export interface TreeDraggableConfig {
  /** `false` 显式关闭拖拽把手（默认渲染 HolderOutlined）。 */
  icon?: VNodeChild | false;
  nodeDraggable?: TreeNodeDraggableFn;
}
export type TreeDraggable = TreeNodeDraggableFn | boolean | TreeDraggableConfig;
```

## line (line)

带连接线的树（`showLine`），可配置节点图标。

### line.vue

```vue
<script setup lang="ts">
import { CarryOutOutlined, SmileOutlined } from '@apollo-design/icons';
import { Tree } from '@apollo-design/ui';
import { h } from 'vue';

const treeData = [
  {
    title: 'parent 1',
    key: '0-0',
    icon: () => h(CarryOutOutlined),
    children: [
      { title: 'leaf', key: '0-0-0', icon: () => h(CarryOutOutlined) },
      { title: 'leaf', key: '0-0-1', icon: () => h(SmileOutlined) },
    ],
  },
];
</script>

<template>
  <Tree show-line :default-expanded-keys="['0-0-0']" :tree-data="treeData" />
</template>
```

## line-debug (line-debug)

调试连接线样式的专用示例。

### line-debug.vue

```vue
<script setup lang="ts">
import { Tree } from '@apollo-design/ui';

const treeData = [
  {
    title: 'parent 1',
    key: '0-0',
    children: [
      { title: 'leaf 1', key: '0-0-0', isLeaf: true },
      {
        title: 'parent 1-1',
        key: '0-0-1',
        children: [{ title: 'leaf', key: '0-0-1-0', isLeaf: true }],
      },
    ],
  },
];
</script>

<template>
  <Tree :tree-data="treeData" default-expand-all show-line />
</template>
```

## multiple-line (multiple-line)

节点标题多行展示（配合 `block-node`）。

### multiple-line.vue

```vue
<script setup lang="ts">
import { Tree } from '@apollo-design/ui';

const treeData = [
  {
    title: 'parent 1',
    key: '0-0',
    children: [
      {
        title:
          'multiple line title multiple line title multiple line title multiple line title multiple line title',
        key: '0-0-0',
      },
      { title: 'short title', key: '0-0-1' },
    ],
  },
];
</script>

<template>
  <Tree :tree-data="treeData" default-expand-all block-node />
</template>
```

## scroll-to (scroll-to)

展开目标节点的祖先并在 63 个节点中滚动定位；复位按钮收起目录并滚回顶部。

### scroll-to.vue

```vue
<script setup lang="ts">
import { Button, Space, Tree, type TreeRef } from '@apollo-design/ui';
import { nextTick, ref } from 'vue';
import type { DataNode, TreeKey } from '../interface';

const TARGET_KEY = 'target';
const treeRef = ref<TreeRef | null>(null);
const expandedKeys = ref<TreeKey[]>([]);
const treeData: DataNode[] = [
  ...Array.from({ length: 60 }, (_, index) => ({
    key: `row-${index}`,
    title: `节点 ${index + 1}`,
  })),
  {
    key: 'folder',
    title: '目标文件夹',
    children: [
      {
        key: 'nested',
        title: '子文件夹',
        children: [{ key: TARGET_KEY, title: '目标节点', isLeaf: true }],
      },
    ],
  },
];
const scrollTo = () =>
  treeRef.value?.scrollTo({ key: TARGET_KEY, autoExpand: true, align: 'bottom' });
const reset = async () => {
  expandedKeys.value = [];
  await nextTick();
  treeRef.value?.scrollTo(0);
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px">
    <Space wrap><Button @click="scrollTo">展开并定位到目标节点</Button><Button @click="reset">复位</Button></Space>
    <Tree ref="treeRef" v-model:expanded-keys="expandedKeys" :height="200" :tree-data="treeData" />
  </div>
</template>
```

### ../interface.ts

```ts
import type { CSSProperties, VNodeChild } from 'vue';
import type {
  BasicDataNode,
  DataNode,
  EventDataNode,
  SafeKey,
  TreeDataEntity,
  TreeDraggable,
  TreeExpandAction,
  TreeFieldNames,
  TreeIconType,
  TreeKey,
} from '../_internal/tree/types';

// ── 数据模型的定义已搬到 packages/ui/src/_internal/tree/types.ts ──────────────
//
// 裁决 `early-extract-table-core-tree-core` = **C**（2026-10-07）：`tree` 的纯逻辑
// （键实体表 / 勾选传导 / 数组增删）有 ≥2 个消费者（`tree-select` / `table`），
// 按「共享工具必须放 `src/_internal/`」该搬出组件目录；而那些逻辑**依赖这份数据模型**
// ⇒ 只搬函数会造成 `_internal/ → tree/` 的反向依赖，比原状更糟。所以类型跟着一起搬。
//
// ⚠️ 下面这一句**不能删**：它保证公开 API 面与所有既有的 `tree/interface` 导入站点
//    完全不变（`FieldDataNode` / `TreeNodeRenderInfo` / `TreeNodeDraggableFn` /
//    `TreeDraggableConfig` 本文件已不再直接使用，但仍是对外契约的一部分）。
export type {
  BasicDataNode,
  DataNode,
  EventDataNode,
  FieldDataNode,
  SafeKey,
  TreeDataEntity,
  TreeDraggable,
  TreeDraggableConfig,
  TreeExpandAction,
  TreeFieldNames,
  TreeIconType,
  TreeKey,
  TreeNodeDraggableFn,
  TreeNodeRenderInfo,
} from '../_internal/tree/types';

/** rc `AllowDrop`。 */
export interface TreeAllowDropOptions<TreeDataType extends BasicDataNode = DataNode> {
  dragNode: TreeDataType;
  dropNode: TreeDataType;
  dropPosition: -1 | 0 | 1;
}
export type TreeAllowDrop<TreeDataType extends BasicDataNode = DataNode> = (
  options: TreeAllowDropOptions<TreeDataType>,
) => boolean;

// ---------------------------------------------------------------------------
// 事件信息（rc 逐字段）
// ---------------------------------------------------------------------------

export interface TreeExpandEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  node: EventDataNode<TreeDataType>;
  expanded: boolean;
  nativeEvent: MouseEvent | KeyboardEvent;
}

export interface TreeCheckInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'check';
  node: EventDataNode<TreeDataType>;
  checked: boolean;
  nativeEvent: MouseEvent | KeyboardEvent;
  checkedNodes: TreeDataType[];
  /** 仅非 checkStrictly（级联）时携带（rc [Legacy]，tree-select 依赖）。 */
  checkedNodesPositions?: { node: TreeDataType; pos: string }[];
  halfCheckedKeys?: SafeKey[];
}

export interface TreeSelectEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'select';
  selected: boolean;
  node: EventDataNode<TreeDataType>;
  selectedNodes: TreeDataType[];
  nativeEvent: MouseEvent | KeyboardEvent;
}

export interface TreeLoadEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'load';
  node: EventDataNode<TreeDataType>;
}

export interface TreeDragEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  node: EventDataNode<TreeDataType>;
}

export interface TreeDragEnterEventInfo<TreeDataType extends BasicDataNode = DataNode>
  extends TreeDragEventInfo<TreeDataType> {
  expandedKeys: TreeKey[];
}

export interface TreeDropEventInfo<TreeDataType extends BasicDataNode = DataNode>
  extends TreeDragEventInfo<TreeDataType> {
  dragNode: EventDataNode<TreeDataType>;
  dragNodesKeys: TreeKey[];
  dropPosition: number;
  dropToGap: boolean;
}

// ---------------------------------------------------------------------------
// 语义化槽位（5 个；antd `TreeSemanticType`）
// ---------------------------------------------------------------------------

export interface TreeSemanticClassNames {
  root?: string;
  item?: string;
  itemIcon?: string;
  itemTitle?: string;
  itemSwitcher?: string;
}

export interface TreeSemanticStyles {
  root?: CSSProperties;
  item?: CSSProperties;
  itemIcon?: CSSProperties;
  itemTitle?: CSSProperties;
  itemSwitcher?: CSSProperties;
}

/** 函数形态（裁决 `empty-semantic-fn` = B）。 */
export type TreeSemanticValue<T> = T | ((info: { props: TreeProps }) => T);

// ---------------------------------------------------------------------------
// Props（antd 面 = Omit<rc TreeProps, ...> + antd 追加）
// ---------------------------------------------------------------------------

/** rc `checkedKeys` 的对象形态。 */
export interface TreeCheckedKeys {
  checked: SafeKey[];
  halfChecked: SafeKey[];
}

/**
 * `scrollTo` 的参数（rc 的 `ScrollTo` 配置：数字 / `{ key, autoExpand? }` / 对齐配置）。
 *
 * 🚨 **字段名是 `align`，不是 DOM `scrollIntoView` 的 `block` / `inline`**（2026-09-30 修）：
 *    原来这里写了 `block` / `inline`，但
 *      ①文档 `index.zh-CN.md` 的方法表写的是 `scrollTo({ key, autoExpand?, offset?, align? })`；
 *      ②实现（`Tree.ts` → `NodeList.ts`）把配置**原样透传**给 `@apollo-design/virtual-list`，
 *        而它的 `ScrollAlign = 'top' | 'bottom'`（对拍 rc-virtual-list）；
 *    三方只有本接口不一致 ⇒ 调用方按文档写 `align: 'top'` 会被类型系统拒绝
 *    （demo `scroll-to.vue` 就是这样暴露出来的），按接口写 `block` 则**静默失效**。
 *
 * ⚠️ 值域只到 `'top' | 'bottom'`（本仓 virtual-list 的 `ScrollAlign`），没有 `'auto'`。
 */
export interface TreeScrollConfig {
  key: TreeKey;
  autoExpand?: boolean;
  /** 距视口顶部的附加偏移（rc `itemScrollOffset`）。 */
  offset?: number;
  /** 对齐方式：贴顶 / 贴底。缺省时不滚动（见 virtual-list 的 scroll-target 契约）。 */
  align?: 'top' | 'bottom';
}

export interface TreeProps<TreeDataType extends object = object> {
  // ---- 数据 ----
  /** 树数据（v6 主通道；`<TreeNode>` children 形态已 deprecated，不实现）。 */
  treeData?: TreeDataType[];
  /** 字段名映射（title / key / children）。 */
  fieldNames?: TreeFieldNames;

  // ---- 展开态 ----
  expandedKeys?: TreeKey[];
  defaultExpandedKeys?: TreeKey[];
  /** 默认展开全部（**只展开有 children 的节点** —— rc gDSFP 判据）。 */
  defaultExpandAll?: boolean;
  /** 默认展开父节点（受控 expandedKeys 首挂时也 conductExpandParent 补全祖先）。 */
  defaultExpandParent?: boolean;
  /** 展开受控时自动补全祖先（autoExpandParent）。 */
  autoExpandParent?: boolean;

  // ---- 勾选态 ----
  checkable?: boolean | VNodeChild;
  checkStrictly?: boolean;
  checkedKeys?: SafeKey[] | TreeCheckedKeys;
  defaultCheckedKeys?: SafeKey[];

  // ---- 选中态 ----
  selectable?: boolean;
  multiple?: boolean;
  selectedKeys?: TreeKey[];
  defaultSelectedKeys?: TreeKey[];

  // ---- 异步加载 ----
  loadData?: (node: EventDataNode) => Promise<unknown>;
  loadedKeys?: SafeKey[];

  // ---- 外观 ----
  showIcon?: boolean;
  showLine?: boolean | { showLeafIcon: boolean | TreeIconType };
  icon?: VNodeChild;
  switcherIcon?: VNodeChild;
  switcherLoadingIcon?: VNodeChild;
  blockNode?: boolean;
  /** 点击/双击节点时是否触发展开（DirectoryTree 默认 'click'）。 */
  expandAction?: TreeExpandAction;

  // ---- 禁用 / 拖拽 ----
  disabled?: boolean;
  draggable?: TreeDraggable;
  allowDrop?: TreeAllowDrop;

  // ---- 滚动 / 虚拟 ----
  /** 虚拟滚动容器高度（不传则不虚拟）。 */
  height?: number;
  /** 行高（antd 用 `paddingXS/2 + titleHeight` 计算，勿手传）。 */
  itemHeight?: number;
  scrollWidth?: number;
  virtual?: boolean;
  /** activeKey 滚动跟随时的附加偏移。 */
  itemScrollOffset?: number;

  // ---- 焦点 / ARIA ----
  focusable?: boolean;
  activeKey?: TreeKey | null;
  tabIndex?: number;
  /** rc 自述「TODO: full a11y」—— 现状键盘可达 + active 跟随；无 tree role（UPSTREAM）。 */

  // ---- 过滤 ----
  filterTreeNode?: (node: EventDataNode) => boolean;

  // ---- 常规 ----
  prefixCls?: string;
  /** @deprecated 请用 `styles.root`（antd v6 标记）。 */
  rootStyle?: CSSProperties;
  classNames?: TreeSemanticValue<TreeSemanticClassNames>;
  styles?: TreeSemanticValue<TreeSemanticStyles>;
}

// ---------------------------------------------------------------------------
// Emits（C11：v-model 与语义事件同发）
// ---------------------------------------------------------------------------

export interface TreeEmits {
  /** `v-model:expandedKeys`。 */
  (e: 'update:expandedKeys', keys: TreeKey[]): void;
  /** `v-model:checkedKeys`；checkStrictly 时为对象形态。 */
  (e: 'update:checkedKeys', keys: SafeKey[] | TreeCheckedKeys): void;
  /** `v-model:selectedKeys`。 */
  (e: 'update:selectedKeys', keys: TreeKey[]): void;
  /** `v-model:loadedKeys`。 */
  (e: 'update:loadedKeys', keys: SafeKey[]): void;
  (e: 'update:activeKey', key: TreeKey | null): void;
  (e: 'activeChange', key: TreeKey | null): void;
  /** 展开/收起（与 `update:expandedKeys` 同发）。 */
  (e: 'expand', keys: TreeKey[], info: TreeExpandEventInfo): void;
  /** 勾选（与 `update:checkedKeys` 同发；返回值形态随 checkStrictly）。 */
  (e: 'check', checked: SafeKey[] | TreeCheckedKeys, info: TreeCheckInfo): void;
  /** 选中（与 `update:selectedKeys` 同发）。 */
  (e: 'select', keys: TreeKey[], info: TreeSelectEventInfo): void;
  /** 异步加载完成（与 `update:loadedKeys` 同发）。 */
  (e: 'load', keys: SafeKey[], info: TreeLoadEventInfo): void;
  (e: 'click', evt: MouseEvent, node: EventDataNode): void;
  (e: 'doubleClick', evt: MouseEvent, node: EventDataNode): void;
  (e: 'contextmenu', evt: MouseEvent, node: EventDataNode): void;
  (e: 'mouseEnter', evt: MouseEvent, node: EventDataNode): void;
  (e: 'mouseLeave', evt: MouseEvent, node: EventDataNode): void;
  (e: 'dragStart', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragEnter', evt: DragEvent, info: TreeDragEnterEventInfo): void;
  (e: 'dragOver', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragLeave', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragEnd', evt: DragEvent, info: { node: EventDataNode | null }): void;
  (e: 'drop', evt: DragEvent, info: TreeDropEventInfo): void;
}

// ---------------------------------------------------------------------------
// Slots
// ---------------------------------------------------------------------------

export interface TreeSlotScope<TreeDataType extends object = Record<string, unknown>> {
  node: EventDataNode;
  data: TreeDataType;
}

export interface TreeSlots<TreeDataType extends object = Record<string, unknown>> {
  /** Slot presence takes priority, including an intentionally empty result. */
  title?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  icon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  switcherIcon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  switcherLoadingIcon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
}

// ---------------------------------------------------------------------------
// Expose（rc class 实例的公开方法面）
// ---------------------------------------------------------------------------

export interface TreeRef<TreeDataType extends object = DataNode> {
  /** 滚动到指定节点；`autoExpand: true` 时先展开再滚。 */
  scrollTo: (scroll?: number | TreeScrollConfig | null) => void;
  /** 聚焦树容器（rc focusable 管理）。 */
  focus: () => void;
  /** 节点数据实体表（只读快照）。 */
  keyEntities: Record<SafeKey, TreeDataEntity<TreeDataType>>;
}

// ---------------------------------------------------------------------------
// DirectoryTree
// ---------------------------------------------------------------------------

/**
 * DirectoryTree 的 props：与 TreeProps 相同，但**默认值不同**（G1 §4）——
 * `showIcon=true` / `expandAction='click'` / `blockNode=true` / `defaultExpandParent=true`
 * + shift/ctrl 范围多选 + File/Folder 图标。类型上直接复用 {@link TreeProps}。
 */
export type DirectoryTreeProps = TreeProps;
```

### ../../_internal/tree/types.ts

```ts
/**
 * Tree 数据模型的**共享类型**。
 *
 * ── 为什么这份类型不在 `packages/ui/src/tree/interface.ts` 里 ──────────────────
 *
 * 裁决 `early-extract-table-core-tree-core` = **C**（2026-10-07 用户裁决）：
 * `tree` 的纯逻辑（键实体表 / 勾选传导 / 数组增删）有 **≥2 个消费者**
 * （`tree-select` 与 `table`），按本仓「共享工具必须放 `src/_internal/`」的准则
 * 该搬出组件目录。
 *
 * 但那些逻辑**依赖这份数据模型** —— 只搬函数、把类型留在 `tree/interface.ts`，
 * 就会造出 `_internal/ → tree/` 的**反向依赖**，比原来的「组件间互 import」更糟。
 * ⇒ 所以**类型跟着逻辑一起搬**。
 *
 * `tree/interface.ts` 会把它们原样再导出
 * （`export type { … } from '../_internal/tree/types'`）
 * ⇒ 公开 API 面与所有既有的 `tree/interface` 导入站点**都不受影响**。
 *
 * 契约来源：antd 6.6.4 `es/tree/Tree.d.ts` + `@rc-component/tree` 1.4.0 的
 * `Tree.d.ts` / `interface.d.ts`。分析见 `docs/analysis/tree.md`。
 *
 * ⚠️ 禁止 any / as any / @ts-expect-error（H10）。
 */

import type { CSSProperties, VNodeChild } from 'vue';

/** `React.Key` 的 Vue 对应物；`SafeKey` 排除 bigint（rc :88-95 的既有约束）。 */
export type TreeKey = string | number;
export type SafeKey = Exclude<TreeKey, bigint>;

/** rc `FieldDataNode`：用户数据节点 + 递归 children（字段名可由 fieldNames 改写）。 */
export interface BasicDataNode {
  checkable?: boolean;
  disabled?: boolean;
  disableCheckbox?: boolean;
  icon?: TreeIconType;
  isLeaf?: boolean;
  selectable?: boolean;
  switcherIcon?: TreeIconType;
  className?: string;
  style?: CSSProperties;
}

export type FieldDataNode<T, ChildFieldName extends string = 'children'> = BasicDataNode &
  T &
  Partial<Record<ChildFieldName, FieldDataNode<T, ChildFieldName>[]>>;

/** rc `DataNode`（默认字段名形态）。 */
export type DataNode = FieldDataNode<{
  key: TreeKey;
  title?: VNodeChild | ((data: DataNode) => VNodeChild);
}>;

/** rc `EventDataNode`：事件回调里的节点（数据 + 运行时态）。 */
export type EventDataNode<TreeDataType extends BasicDataNode = DataNode> = {
  key: TreeKey;
  expanded: boolean;
  selected: boolean;
  checked: boolean;
  loaded: boolean;
  loading: boolean;
  halfChecked: boolean;
  dragOver: boolean;
  dragOverGapTop: boolean;
  dragOverGapBottom: boolean;
  pos: string;
  active: boolean;
} & TreeDataType &
  BasicDataNode;

/** rc `FieldNames`（`_title` 仅 tree-select 内部使用，保留字段不公开）。 */
export interface TreeFieldNames {
  title?: string;
  key?: string;
  children?: string;
}

/** rc `DataEntity`（键实体表值；keyEntities 的公开形态）。 */
export interface TreeDataEntity<TreeDataType extends object = DataNode> {
  index: number;
  key: SafeKey;
  pos: string;
  level: number;
  node: TreeDataType;
  nodes: TreeDataType[];
  children?: TreeDataEntity<TreeDataType>[];
  parent?: TreeDataEntity<TreeDataType>;
}

/** 节点态传给 icon/switcherIcon fn 的参数（rc `TreeNodeProps` 的只读子集）。 */
export interface TreeNodeRenderInfo<TreeDataType extends object = Record<string, unknown>> {
  eventKey?: TreeKey;
  expanded?: boolean;
  selected?: boolean;
  checked?: boolean;
  loaded?: boolean;
  loading?: boolean;
  halfChecked?: boolean;
  dragOver?: boolean;
  dragOverGapTop?: boolean;
  dragOverGapBottom?: boolean;
  pos?: string;
  data?: TreeDataType;
  isLeaf?: boolean;
  checkable?: boolean;
  selectable?: boolean;
  disabled?: boolean;
  disableCheckbox?: boolean;
  /** 展开函数等注入位与 rc 的 treeNodeProps 同构。 */
  [key: string]: unknown;
}

/** rc `IconType`：VNode 或按节点态求值的 fn。 */
export type TreeIconType<TreeDataType extends object = Record<string, unknown>> =
  | VNodeChild
  | ((props: TreeNodeRenderInfo<TreeDataType>) => VNodeChild);

/** rc `ExpandAction`。 */
export type TreeExpandAction = false | 'click' | 'doubleClick';

/** rc `DraggableFn` / `DraggableConfig`。 */
export type TreeNodeDraggableFn = (node: DataNode) => boolean;
export interface TreeDraggableConfig {
  /** `false` 显式关闭拖拽把手（默认渲染 HolderOutlined）。 */
  icon?: VNodeChild | false;
  nodeDraggable?: TreeNodeDraggableFn;
}
export type TreeDraggable = TreeNodeDraggableFn | boolean | TreeDraggableConfig;
```

## search (search)

可搜索的树（匹配节点自动展开父级）。

### search.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 search demo。⚠️ 用**公开的 `DataNode`** 标注，别让 TS 推断成
// `children?: unknown[]` —— 那样传给 `:tree-data` 会报「不可赋值给 DataNode[]」。
import { Input, Tree } from '@apollo-design/ui';
import { ref } from 'vue';
// ⚠️ `DataNode` / `EventDataNode` **不在包根导出**（根 barrel 只导 `Tree*` 前缀的类型）
//    ⇒ 从组件的本地模块导入；写成 `from '@apollo-design/ui'` 会报 TS2305。
import type { DataNode, TreeKey } from '../interface';

const x = 3,
  y = 2,
  z = 1;
const defaultData: DataNode[] = [];
const generateData = (_level: number, preKey = '0', tns: DataNode[] = defaultData): void => {
  const children: string[] = [];
  for (let i = 0; i < x; i += 1) {
    const key = `${preKey}-${i}`;
    tns.push({ title: key, key });
    if (i < y) children.push(key);
  }
  if (_level < 0) return;
  const level = _level - 1;
  for (const [index, key] of children.entries()) {
    const node = tns[index];
    if (!node) continue;
    node.children = [];
    generateData(level, key, node.children);
  }
};
generateData(z);

// ⚠️ 节点 key 的类型是公开的 `TreeKey`（`string | number`），不是 `string`。
const dataList: { key: TreeKey; title: string }[] = [];
const generateList = (data: DataNode[]): void => {
  for (const node of data) {
    dataList.push({ key: node.key, title: String(node.key) });
    if (node.children) generateList(node.children);
  }
};
generateList(defaultData);

const getParentKey = (key: TreeKey, tree: DataNode[]): TreeKey | undefined => {
  let parentKey: TreeKey | undefined;
  for (const node of tree) {
    if (!node.children) continue;
    if (node.children.some((item) => item.key === key)) {
      parentKey = node.key;
    } else {
      const nested = getParentKey(key, node.children);
      if (nested) parentKey = nested;
    }
  }
  return parentKey;
};

const expandedKeys = ref<(string | number)[]>([]);
const searchValue = ref('');
const autoExpandParent = ref(true);

const onChange = (value: string): void => {
  // ⚠️ 去重 + 收紧类型：`filter(Boolean)` 会留下 `undefined`（`(string|undefined)[]`
  //    赋不给 `(string|number)[]`），用 Set + 类型守卫表达同一语义。
  const newExpandedKeys = Array.from(
    new Set(
      dataList
        .map((item) =>
          item.title.includes(value) ? getParentKey(item.key, defaultData) : undefined,
        )
        .filter((item): item is string => item !== undefined),
    ),
  );
  expandedKeys.value = newExpandedKeys;
  searchValue.value = value;
  autoExpandParent.value = true;
};
</script>

<template>
  <div>
    <Input :value="searchValue" class="tree-demo-search" aria-label="Search tree nodes" placeholder="Search" allow-clear style="margin-bottom: 8px" @update:value="onChange" />
    <Tree
      :expanded-keys="expandedKeys"
      :auto-expand-parent="autoExpandParent"
      :tree-data="defaultData"
      @expand="(keys: (string | number)[]) => { expandedKeys = keys; autoExpandParent = false; }"
    />
  </div>
</template>
```

### ../interface.ts

```ts
import type { CSSProperties, VNodeChild } from 'vue';
import type {
  BasicDataNode,
  DataNode,
  EventDataNode,
  SafeKey,
  TreeDataEntity,
  TreeDraggable,
  TreeExpandAction,
  TreeFieldNames,
  TreeIconType,
  TreeKey,
} from '../_internal/tree/types';

// ── 数据模型的定义已搬到 packages/ui/src/_internal/tree/types.ts ──────────────
//
// 裁决 `early-extract-table-core-tree-core` = **C**（2026-10-07）：`tree` 的纯逻辑
// （键实体表 / 勾选传导 / 数组增删）有 ≥2 个消费者（`tree-select` / `table`），
// 按「共享工具必须放 `src/_internal/`」该搬出组件目录；而那些逻辑**依赖这份数据模型**
// ⇒ 只搬函数会造成 `_internal/ → tree/` 的反向依赖，比原状更糟。所以类型跟着一起搬。
//
// ⚠️ 下面这一句**不能删**：它保证公开 API 面与所有既有的 `tree/interface` 导入站点
//    完全不变（`FieldDataNode` / `TreeNodeRenderInfo` / `TreeNodeDraggableFn` /
//    `TreeDraggableConfig` 本文件已不再直接使用，但仍是对外契约的一部分）。
export type {
  BasicDataNode,
  DataNode,
  EventDataNode,
  FieldDataNode,
  SafeKey,
  TreeDataEntity,
  TreeDraggable,
  TreeDraggableConfig,
  TreeExpandAction,
  TreeFieldNames,
  TreeIconType,
  TreeKey,
  TreeNodeDraggableFn,
  TreeNodeRenderInfo,
} from '../_internal/tree/types';

/** rc `AllowDrop`。 */
export interface TreeAllowDropOptions<TreeDataType extends BasicDataNode = DataNode> {
  dragNode: TreeDataType;
  dropNode: TreeDataType;
  dropPosition: -1 | 0 | 1;
}
export type TreeAllowDrop<TreeDataType extends BasicDataNode = DataNode> = (
  options: TreeAllowDropOptions<TreeDataType>,
) => boolean;

// ---------------------------------------------------------------------------
// 事件信息（rc 逐字段）
// ---------------------------------------------------------------------------

export interface TreeExpandEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  node: EventDataNode<TreeDataType>;
  expanded: boolean;
  nativeEvent: MouseEvent | KeyboardEvent;
}

export interface TreeCheckInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'check';
  node: EventDataNode<TreeDataType>;
  checked: boolean;
  nativeEvent: MouseEvent | KeyboardEvent;
  checkedNodes: TreeDataType[];
  /** 仅非 checkStrictly（级联）时携带（rc [Legacy]，tree-select 依赖）。 */
  checkedNodesPositions?: { node: TreeDataType; pos: string }[];
  halfCheckedKeys?: SafeKey[];
}

export interface TreeSelectEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'select';
  selected: boolean;
  node: EventDataNode<TreeDataType>;
  selectedNodes: TreeDataType[];
  nativeEvent: MouseEvent | KeyboardEvent;
}

export interface TreeLoadEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'load';
  node: EventDataNode<TreeDataType>;
}

export interface TreeDragEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  node: EventDataNode<TreeDataType>;
}

export interface TreeDragEnterEventInfo<TreeDataType extends BasicDataNode = DataNode>
  extends TreeDragEventInfo<TreeDataType> {
  expandedKeys: TreeKey[];
}

export interface TreeDropEventInfo<TreeDataType extends BasicDataNode = DataNode>
  extends TreeDragEventInfo<TreeDataType> {
  dragNode: EventDataNode<TreeDataType>;
  dragNodesKeys: TreeKey[];
  dropPosition: number;
  dropToGap: boolean;
}

// ---------------------------------------------------------------------------
// 语义化槽位（5 个；antd `TreeSemanticType`）
// ---------------------------------------------------------------------------

export interface TreeSemanticClassNames {
  root?: string;
  item?: string;
  itemIcon?: string;
  itemTitle?: string;
  itemSwitcher?: string;
}

export interface TreeSemanticStyles {
  root?: CSSProperties;
  item?: CSSProperties;
  itemIcon?: CSSProperties;
  itemTitle?: CSSProperties;
  itemSwitcher?: CSSProperties;
}

/** 函数形态（裁决 `empty-semantic-fn` = B）。 */
export type TreeSemanticValue<T> = T | ((info: { props: TreeProps }) => T);

// ---------------------------------------------------------------------------
// Props（antd 面 = Omit<rc TreeProps, ...> + antd 追加）
// ---------------------------------------------------------------------------

/** rc `checkedKeys` 的对象形态。 */
export interface TreeCheckedKeys {
  checked: SafeKey[];
  halfChecked: SafeKey[];
}

/**
 * `scrollTo` 的参数（rc 的 `ScrollTo` 配置：数字 / `{ key, autoExpand? }` / 对齐配置）。
 *
 * 🚨 **字段名是 `align`，不是 DOM `scrollIntoView` 的 `block` / `inline`**（2026-09-30 修）：
 *    原来这里写了 `block` / `inline`，但
 *      ①文档 `index.zh-CN.md` 的方法表写的是 `scrollTo({ key, autoExpand?, offset?, align? })`；
 *      ②实现（`Tree.ts` → `NodeList.ts`）把配置**原样透传**给 `@apollo-design/virtual-list`，
 *        而它的 `ScrollAlign = 'top' | 'bottom'`（对拍 rc-virtual-list）；
 *    三方只有本接口不一致 ⇒ 调用方按文档写 `align: 'top'` 会被类型系统拒绝
 *    （demo `scroll-to.vue` 就是这样暴露出来的），按接口写 `block` 则**静默失效**。
 *
 * ⚠️ 值域只到 `'top' | 'bottom'`（本仓 virtual-list 的 `ScrollAlign`），没有 `'auto'`。
 */
export interface TreeScrollConfig {
  key: TreeKey;
  autoExpand?: boolean;
  /** 距视口顶部的附加偏移（rc `itemScrollOffset`）。 */
  offset?: number;
  /** 对齐方式：贴顶 / 贴底。缺省时不滚动（见 virtual-list 的 scroll-target 契约）。 */
  align?: 'top' | 'bottom';
}

export interface TreeProps<TreeDataType extends object = object> {
  // ---- 数据 ----
  /** 树数据（v6 主通道；`<TreeNode>` children 形态已 deprecated，不实现）。 */
  treeData?: TreeDataType[];
  /** 字段名映射（title / key / children）。 */
  fieldNames?: TreeFieldNames;

  // ---- 展开态 ----
  expandedKeys?: TreeKey[];
  defaultExpandedKeys?: TreeKey[];
  /** 默认展开全部（**只展开有 children 的节点** —— rc gDSFP 判据）。 */
  defaultExpandAll?: boolean;
  /** 默认展开父节点（受控 expandedKeys 首挂时也 conductExpandParent 补全祖先）。 */
  defaultExpandParent?: boolean;
  /** 展开受控时自动补全祖先（autoExpandParent）。 */
  autoExpandParent?: boolean;

  // ---- 勾选态 ----
  checkable?: boolean | VNodeChild;
  checkStrictly?: boolean;
  checkedKeys?: SafeKey[] | TreeCheckedKeys;
  defaultCheckedKeys?: SafeKey[];

  // ---- 选中态 ----
  selectable?: boolean;
  multiple?: boolean;
  selectedKeys?: TreeKey[];
  defaultSelectedKeys?: TreeKey[];

  // ---- 异步加载 ----
  loadData?: (node: EventDataNode) => Promise<unknown>;
  loadedKeys?: SafeKey[];

  // ---- 外观 ----
  showIcon?: boolean;
  showLine?: boolean | { showLeafIcon: boolean | TreeIconType };
  icon?: VNodeChild;
  switcherIcon?: VNodeChild;
  switcherLoadingIcon?: VNodeChild;
  blockNode?: boolean;
  /** 点击/双击节点时是否触发展开（DirectoryTree 默认 'click'）。 */
  expandAction?: TreeExpandAction;

  // ---- 禁用 / 拖拽 ----
  disabled?: boolean;
  draggable?: TreeDraggable;
  allowDrop?: TreeAllowDrop;

  // ---- 滚动 / 虚拟 ----
  /** 虚拟滚动容器高度（不传则不虚拟）。 */
  height?: number;
  /** 行高（antd 用 `paddingXS/2 + titleHeight` 计算，勿手传）。 */
  itemHeight?: number;
  scrollWidth?: number;
  virtual?: boolean;
  /** activeKey 滚动跟随时的附加偏移。 */
  itemScrollOffset?: number;

  // ---- 焦点 / ARIA ----
  focusable?: boolean;
  activeKey?: TreeKey | null;
  tabIndex?: number;
  /** rc 自述「TODO: full a11y」—— 现状键盘可达 + active 跟随；无 tree role（UPSTREAM）。 */

  // ---- 过滤 ----
  filterTreeNode?: (node: EventDataNode) => boolean;

  // ---- 常规 ----
  prefixCls?: string;
  /** @deprecated 请用 `styles.root`（antd v6 标记）。 */
  rootStyle?: CSSProperties;
  classNames?: TreeSemanticValue<TreeSemanticClassNames>;
  styles?: TreeSemanticValue<TreeSemanticStyles>;
}

// ---------------------------------------------------------------------------
// Emits（C11：v-model 与语义事件同发）
// ---------------------------------------------------------------------------

export interface TreeEmits {
  /** `v-model:expandedKeys`。 */
  (e: 'update:expandedKeys', keys: TreeKey[]): void;
  /** `v-model:checkedKeys`；checkStrictly 时为对象形态。 */
  (e: 'update:checkedKeys', keys: SafeKey[] | TreeCheckedKeys): void;
  /** `v-model:selectedKeys`。 */
  (e: 'update:selectedKeys', keys: TreeKey[]): void;
  /** `v-model:loadedKeys`。 */
  (e: 'update:loadedKeys', keys: SafeKey[]): void;
  (e: 'update:activeKey', key: TreeKey | null): void;
  (e: 'activeChange', key: TreeKey | null): void;
  /** 展开/收起（与 `update:expandedKeys` 同发）。 */
  (e: 'expand', keys: TreeKey[], info: TreeExpandEventInfo): void;
  /** 勾选（与 `update:checkedKeys` 同发；返回值形态随 checkStrictly）。 */
  (e: 'check', checked: SafeKey[] | TreeCheckedKeys, info: TreeCheckInfo): void;
  /** 选中（与 `update:selectedKeys` 同发）。 */
  (e: 'select', keys: TreeKey[], info: TreeSelectEventInfo): void;
  /** 异步加载完成（与 `update:loadedKeys` 同发）。 */
  (e: 'load', keys: SafeKey[], info: TreeLoadEventInfo): void;
  (e: 'click', evt: MouseEvent, node: EventDataNode): void;
  (e: 'doubleClick', evt: MouseEvent, node: EventDataNode): void;
  (e: 'contextmenu', evt: MouseEvent, node: EventDataNode): void;
  (e: 'mouseEnter', evt: MouseEvent, node: EventDataNode): void;
  (e: 'mouseLeave', evt: MouseEvent, node: EventDataNode): void;
  (e: 'dragStart', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragEnter', evt: DragEvent, info: TreeDragEnterEventInfo): void;
  (e: 'dragOver', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragLeave', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragEnd', evt: DragEvent, info: { node: EventDataNode | null }): void;
  (e: 'drop', evt: DragEvent, info: TreeDropEventInfo): void;
}

// ---------------------------------------------------------------------------
// Slots
// ---------------------------------------------------------------------------

export interface TreeSlotScope<TreeDataType extends object = Record<string, unknown>> {
  node: EventDataNode;
  data: TreeDataType;
}

export interface TreeSlots<TreeDataType extends object = Record<string, unknown>> {
  /** Slot presence takes priority, including an intentionally empty result. */
  title?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  icon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  switcherIcon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  switcherLoadingIcon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
}

// ---------------------------------------------------------------------------
// Expose（rc class 实例的公开方法面）
// ---------------------------------------------------------------------------

export interface TreeRef<TreeDataType extends object = DataNode> {
  /** 滚动到指定节点；`autoExpand: true` 时先展开再滚。 */
  scrollTo: (scroll?: number | TreeScrollConfig | null) => void;
  /** 聚焦树容器（rc focusable 管理）。 */
  focus: () => void;
  /** 节点数据实体表（只读快照）。 */
  keyEntities: Record<SafeKey, TreeDataEntity<TreeDataType>>;
}

// ---------------------------------------------------------------------------
// DirectoryTree
// ---------------------------------------------------------------------------

/**
 * DirectoryTree 的 props：与 TreeProps 相同，但**默认值不同**（G1 §4）——
 * `showIcon=true` / `expandAction='click'` / `blockNode=true` / `defaultExpandParent=true`
 * + shift/ctrl 范围多选 + File/Folder 图标。类型上直接复用 {@link TreeProps}。
 */
export type DirectoryTreeProps = TreeProps;
```

### ../../_internal/tree/types.ts

```ts
/**
 * Tree 数据模型的**共享类型**。
 *
 * ── 为什么这份类型不在 `packages/ui/src/tree/interface.ts` 里 ──────────────────
 *
 * 裁决 `early-extract-table-core-tree-core` = **C**（2026-10-07 用户裁决）：
 * `tree` 的纯逻辑（键实体表 / 勾选传导 / 数组增删）有 **≥2 个消费者**
 * （`tree-select` 与 `table`），按本仓「共享工具必须放 `src/_internal/`」的准则
 * 该搬出组件目录。
 *
 * 但那些逻辑**依赖这份数据模型** —— 只搬函数、把类型留在 `tree/interface.ts`，
 * 就会造出 `_internal/ → tree/` 的**反向依赖**，比原来的「组件间互 import」更糟。
 * ⇒ 所以**类型跟着逻辑一起搬**。
 *
 * `tree/interface.ts` 会把它们原样再导出
 * （`export type { … } from '../_internal/tree/types'`）
 * ⇒ 公开 API 面与所有既有的 `tree/interface` 导入站点**都不受影响**。
 *
 * 契约来源：antd 6.6.4 `es/tree/Tree.d.ts` + `@rc-component/tree` 1.4.0 的
 * `Tree.d.ts` / `interface.d.ts`。分析见 `docs/analysis/tree.md`。
 *
 * ⚠️ 禁止 any / as any / @ts-expect-error（H10）。
 */

import type { CSSProperties, VNodeChild } from 'vue';

/** `React.Key` 的 Vue 对应物；`SafeKey` 排除 bigint（rc :88-95 的既有约束）。 */
export type TreeKey = string | number;
export type SafeKey = Exclude<TreeKey, bigint>;

/** rc `FieldDataNode`：用户数据节点 + 递归 children（字段名可由 fieldNames 改写）。 */
export interface BasicDataNode {
  checkable?: boolean;
  disabled?: boolean;
  disableCheckbox?: boolean;
  icon?: TreeIconType;
  isLeaf?: boolean;
  selectable?: boolean;
  switcherIcon?: TreeIconType;
  className?: string;
  style?: CSSProperties;
}

export type FieldDataNode<T, ChildFieldName extends string = 'children'> = BasicDataNode &
  T &
  Partial<Record<ChildFieldName, FieldDataNode<T, ChildFieldName>[]>>;

/** rc `DataNode`（默认字段名形态）。 */
export type DataNode = FieldDataNode<{
  key: TreeKey;
  title?: VNodeChild | ((data: DataNode) => VNodeChild);
}>;

/** rc `EventDataNode`：事件回调里的节点（数据 + 运行时态）。 */
export type EventDataNode<TreeDataType extends BasicDataNode = DataNode> = {
  key: TreeKey;
  expanded: boolean;
  selected: boolean;
  checked: boolean;
  loaded: boolean;
  loading: boolean;
  halfChecked: boolean;
  dragOver: boolean;
  dragOverGapTop: boolean;
  dragOverGapBottom: boolean;
  pos: string;
  active: boolean;
} & TreeDataType &
  BasicDataNode;

/** rc `FieldNames`（`_title` 仅 tree-select 内部使用，保留字段不公开）。 */
export interface TreeFieldNames {
  title?: string;
  key?: string;
  children?: string;
}

/** rc `DataEntity`（键实体表值；keyEntities 的公开形态）。 */
export interface TreeDataEntity<TreeDataType extends object = DataNode> {
  index: number;
  key: SafeKey;
  pos: string;
  level: number;
  node: TreeDataType;
  nodes: TreeDataType[];
  children?: TreeDataEntity<TreeDataType>[];
  parent?: TreeDataEntity<TreeDataType>;
}

/** 节点态传给 icon/switcherIcon fn 的参数（rc `TreeNodeProps` 的只读子集）。 */
export interface TreeNodeRenderInfo<TreeDataType extends object = Record<string, unknown>> {
  eventKey?: TreeKey;
  expanded?: boolean;
  selected?: boolean;
  checked?: boolean;
  loaded?: boolean;
  loading?: boolean;
  halfChecked?: boolean;
  dragOver?: boolean;
  dragOverGapTop?: boolean;
  dragOverGapBottom?: boolean;
  pos?: string;
  data?: TreeDataType;
  isLeaf?: boolean;
  checkable?: boolean;
  selectable?: boolean;
  disabled?: boolean;
  disableCheckbox?: boolean;
  /** 展开函数等注入位与 rc 的 treeNodeProps 同构。 */
  [key: string]: unknown;
}

/** rc `IconType`：VNode 或按节点态求值的 fn。 */
export type TreeIconType<TreeDataType extends object = Record<string, unknown>> =
  | VNodeChild
  | ((props: TreeNodeRenderInfo<TreeDataType>) => VNodeChild);

/** rc `ExpandAction`。 */
export type TreeExpandAction = false | 'click' | 'doubleClick';

/** rc `DraggableFn` / `DraggableConfig`。 */
export type TreeNodeDraggableFn = (node: DataNode) => boolean;
export interface TreeDraggableConfig {
  /** `false` 显式关闭拖拽把手（默认渲染 HolderOutlined）。 */
  icon?: VNodeChild | false;
  nodeDraggable?: TreeNodeDraggableFn;
}
export type TreeDraggable = TreeNodeDraggableFn | boolean | TreeDraggableConfig;
```

## style-class (style-class)

自定义语义化 `classNames` / `styles`（root / item / itemTitle 等 5 槽）。

### style-class.vue

```vue
<script setup lang="ts">
import { Tree } from '@apollo-design/ui';

const treeData = [
  {
    title: 'parent 1',
    key: '0-0',
    children: [
      { title: 'leaf 1', key: '0-0-0' },
      { title: 'leaf 2', key: '0-0-1' },
    ],
  },
];
</script>

<template>
  <Tree
    :tree-data="treeData"
    default-expand-all
    :class-names="{ root: 'my-root', item: 'my-item' }"
    :styles="{ itemTitle: { fontStyle: 'italic' } }"
  />
</template>
```

## switcher-icon (switcher-icon)

自定义展开按钮图标（`switcherIcon`）。

### switcher-icon.vue

```vue
<script setup lang="ts">
import { DownOutlined } from '@apollo-design/icons';
import { Tree } from '@apollo-design/ui';

const treeData = [
  {
    title: 'parent 1',
    key: '0-0',
    children: [{ title: 'leaf', key: '0-0-0' }],
  },
];
</script>

<template>
  <Tree default-expand-all :tree-data="treeData">
    <template #switcherIcon="{ node }"><DownOutlined :data-expanded="node.expanded" /></template>
  </Tree>
</template>
```

## virtual-scroll (virtual-scroll)

指定 `height` 后开启虚拟滚动（只渲染视口内节点）。

### virtual-scroll.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 virtual-scroll demo。
// ⚠️ `build` 必须写**显式返回类型**：递归函数靠推断会报
//    `TS7023/7024: implicitly has return type 'any' because it is referenced directly
//    or indirectly in one of its return expressions`。
import { Tree } from '@apollo-design/ui';
// ⚠️ `DataNode` / `EventDataNode` **不在包根导出**（根 barrel 只导 `Tree*` 前缀的类型）
//    ⇒ 从组件的本地模块导入；写成 `from '@apollo-design/ui'` 会报 TS2305。
import type { DataNode } from '../interface';

const treeData: DataNode[] = [];
const build = (pre: string, level: number): DataNode[] => {
  if (level < 0) return [];
  return [0, 1, 2].map((i) => {
    const key = `${pre}${i}`;
    return { title: `节点 ${key}`, key, children: build(`${key}-`, level - 1) };
  });
};
treeData.push(...build('0-', 3));
</script>

<template>
  <Tree :tree-data="treeData" :height="234" default-expand-all />
</template>
```

### ../interface.ts

```ts
import type { CSSProperties, VNodeChild } from 'vue';
import type {
  BasicDataNode,
  DataNode,
  EventDataNode,
  SafeKey,
  TreeDataEntity,
  TreeDraggable,
  TreeExpandAction,
  TreeFieldNames,
  TreeIconType,
  TreeKey,
} from '../_internal/tree/types';

// ── 数据模型的定义已搬到 packages/ui/src/_internal/tree/types.ts ──────────────
//
// 裁决 `early-extract-table-core-tree-core` = **C**（2026-10-07）：`tree` 的纯逻辑
// （键实体表 / 勾选传导 / 数组增删）有 ≥2 个消费者（`tree-select` / `table`），
// 按「共享工具必须放 `src/_internal/`」该搬出组件目录；而那些逻辑**依赖这份数据模型**
// ⇒ 只搬函数会造成 `_internal/ → tree/` 的反向依赖，比原状更糟。所以类型跟着一起搬。
//
// ⚠️ 下面这一句**不能删**：它保证公开 API 面与所有既有的 `tree/interface` 导入站点
//    完全不变（`FieldDataNode` / `TreeNodeRenderInfo` / `TreeNodeDraggableFn` /
//    `TreeDraggableConfig` 本文件已不再直接使用，但仍是对外契约的一部分）。
export type {
  BasicDataNode,
  DataNode,
  EventDataNode,
  FieldDataNode,
  SafeKey,
  TreeDataEntity,
  TreeDraggable,
  TreeDraggableConfig,
  TreeExpandAction,
  TreeFieldNames,
  TreeIconType,
  TreeKey,
  TreeNodeDraggableFn,
  TreeNodeRenderInfo,
} from '../_internal/tree/types';

/** rc `AllowDrop`。 */
export interface TreeAllowDropOptions<TreeDataType extends BasicDataNode = DataNode> {
  dragNode: TreeDataType;
  dropNode: TreeDataType;
  dropPosition: -1 | 0 | 1;
}
export type TreeAllowDrop<TreeDataType extends BasicDataNode = DataNode> = (
  options: TreeAllowDropOptions<TreeDataType>,
) => boolean;

// ---------------------------------------------------------------------------
// 事件信息（rc 逐字段）
// ---------------------------------------------------------------------------

export interface TreeExpandEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  node: EventDataNode<TreeDataType>;
  expanded: boolean;
  nativeEvent: MouseEvent | KeyboardEvent;
}

export interface TreeCheckInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'check';
  node: EventDataNode<TreeDataType>;
  checked: boolean;
  nativeEvent: MouseEvent | KeyboardEvent;
  checkedNodes: TreeDataType[];
  /** 仅非 checkStrictly（级联）时携带（rc [Legacy]，tree-select 依赖）。 */
  checkedNodesPositions?: { node: TreeDataType; pos: string }[];
  halfCheckedKeys?: SafeKey[];
}

export interface TreeSelectEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'select';
  selected: boolean;
  node: EventDataNode<TreeDataType>;
  selectedNodes: TreeDataType[];
  nativeEvent: MouseEvent | KeyboardEvent;
}

export interface TreeLoadEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  event: 'load';
  node: EventDataNode<TreeDataType>;
}

export interface TreeDragEventInfo<TreeDataType extends BasicDataNode = DataNode> {
  node: EventDataNode<TreeDataType>;
}

export interface TreeDragEnterEventInfo<TreeDataType extends BasicDataNode = DataNode>
  extends TreeDragEventInfo<TreeDataType> {
  expandedKeys: TreeKey[];
}

export interface TreeDropEventInfo<TreeDataType extends BasicDataNode = DataNode>
  extends TreeDragEventInfo<TreeDataType> {
  dragNode: EventDataNode<TreeDataType>;
  dragNodesKeys: TreeKey[];
  dropPosition: number;
  dropToGap: boolean;
}

// ---------------------------------------------------------------------------
// 语义化槽位（5 个；antd `TreeSemanticType`）
// ---------------------------------------------------------------------------

export interface TreeSemanticClassNames {
  root?: string;
  item?: string;
  itemIcon?: string;
  itemTitle?: string;
  itemSwitcher?: string;
}

export interface TreeSemanticStyles {
  root?: CSSProperties;
  item?: CSSProperties;
  itemIcon?: CSSProperties;
  itemTitle?: CSSProperties;
  itemSwitcher?: CSSProperties;
}

/** 函数形态（裁决 `empty-semantic-fn` = B）。 */
export type TreeSemanticValue<T> = T | ((info: { props: TreeProps }) => T);

// ---------------------------------------------------------------------------
// Props（antd 面 = Omit<rc TreeProps, ...> + antd 追加）
// ---------------------------------------------------------------------------

/** rc `checkedKeys` 的对象形态。 */
export interface TreeCheckedKeys {
  checked: SafeKey[];
  halfChecked: SafeKey[];
}

/**
 * `scrollTo` 的参数（rc 的 `ScrollTo` 配置：数字 / `{ key, autoExpand? }` / 对齐配置）。
 *
 * 🚨 **字段名是 `align`，不是 DOM `scrollIntoView` 的 `block` / `inline`**（2026-09-30 修）：
 *    原来这里写了 `block` / `inline`，但
 *      ①文档 `index.zh-CN.md` 的方法表写的是 `scrollTo({ key, autoExpand?, offset?, align? })`；
 *      ②实现（`Tree.ts` → `NodeList.ts`）把配置**原样透传**给 `@apollo-design/virtual-list`，
 *        而它的 `ScrollAlign = 'top' | 'bottom'`（对拍 rc-virtual-list）；
 *    三方只有本接口不一致 ⇒ 调用方按文档写 `align: 'top'` 会被类型系统拒绝
 *    （demo `scroll-to.vue` 就是这样暴露出来的），按接口写 `block` 则**静默失效**。
 *
 * ⚠️ 值域只到 `'top' | 'bottom'`（本仓 virtual-list 的 `ScrollAlign`），没有 `'auto'`。
 */
export interface TreeScrollConfig {
  key: TreeKey;
  autoExpand?: boolean;
  /** 距视口顶部的附加偏移（rc `itemScrollOffset`）。 */
  offset?: number;
  /** 对齐方式：贴顶 / 贴底。缺省时不滚动（见 virtual-list 的 scroll-target 契约）。 */
  align?: 'top' | 'bottom';
}

export interface TreeProps<TreeDataType extends object = object> {
  // ---- 数据 ----
  /** 树数据（v6 主通道；`<TreeNode>` children 形态已 deprecated，不实现）。 */
  treeData?: TreeDataType[];
  /** 字段名映射（title / key / children）。 */
  fieldNames?: TreeFieldNames;

  // ---- 展开态 ----
  expandedKeys?: TreeKey[];
  defaultExpandedKeys?: TreeKey[];
  /** 默认展开全部（**只展开有 children 的节点** —— rc gDSFP 判据）。 */
  defaultExpandAll?: boolean;
  /** 默认展开父节点（受控 expandedKeys 首挂时也 conductExpandParent 补全祖先）。 */
  defaultExpandParent?: boolean;
  /** 展开受控时自动补全祖先（autoExpandParent）。 */
  autoExpandParent?: boolean;

  // ---- 勾选态 ----
  checkable?: boolean | VNodeChild;
  checkStrictly?: boolean;
  checkedKeys?: SafeKey[] | TreeCheckedKeys;
  defaultCheckedKeys?: SafeKey[];

  // ---- 选中态 ----
  selectable?: boolean;
  multiple?: boolean;
  selectedKeys?: TreeKey[];
  defaultSelectedKeys?: TreeKey[];

  // ---- 异步加载 ----
  loadData?: (node: EventDataNode) => Promise<unknown>;
  loadedKeys?: SafeKey[];

  // ---- 外观 ----
  showIcon?: boolean;
  showLine?: boolean | { showLeafIcon: boolean | TreeIconType };
  icon?: VNodeChild;
  switcherIcon?: VNodeChild;
  switcherLoadingIcon?: VNodeChild;
  blockNode?: boolean;
  /** 点击/双击节点时是否触发展开（DirectoryTree 默认 'click'）。 */
  expandAction?: TreeExpandAction;

  // ---- 禁用 / 拖拽 ----
  disabled?: boolean;
  draggable?: TreeDraggable;
  allowDrop?: TreeAllowDrop;

  // ---- 滚动 / 虚拟 ----
  /** 虚拟滚动容器高度（不传则不虚拟）。 */
  height?: number;
  /** 行高（antd 用 `paddingXS/2 + titleHeight` 计算，勿手传）。 */
  itemHeight?: number;
  scrollWidth?: number;
  virtual?: boolean;
  /** activeKey 滚动跟随时的附加偏移。 */
  itemScrollOffset?: number;

  // ---- 焦点 / ARIA ----
  focusable?: boolean;
  activeKey?: TreeKey | null;
  tabIndex?: number;
  /** rc 自述「TODO: full a11y」—— 现状键盘可达 + active 跟随；无 tree role（UPSTREAM）。 */

  // ---- 过滤 ----
  filterTreeNode?: (node: EventDataNode) => boolean;

  // ---- 常规 ----
  prefixCls?: string;
  /** @deprecated 请用 `styles.root`（antd v6 标记）。 */
  rootStyle?: CSSProperties;
  classNames?: TreeSemanticValue<TreeSemanticClassNames>;
  styles?: TreeSemanticValue<TreeSemanticStyles>;
}

// ---------------------------------------------------------------------------
// Emits（C11：v-model 与语义事件同发）
// ---------------------------------------------------------------------------

export interface TreeEmits {
  /** `v-model:expandedKeys`。 */
  (e: 'update:expandedKeys', keys: TreeKey[]): void;
  /** `v-model:checkedKeys`；checkStrictly 时为对象形态。 */
  (e: 'update:checkedKeys', keys: SafeKey[] | TreeCheckedKeys): void;
  /** `v-model:selectedKeys`。 */
  (e: 'update:selectedKeys', keys: TreeKey[]): void;
  /** `v-model:loadedKeys`。 */
  (e: 'update:loadedKeys', keys: SafeKey[]): void;
  (e: 'update:activeKey', key: TreeKey | null): void;
  (e: 'activeChange', key: TreeKey | null): void;
  /** 展开/收起（与 `update:expandedKeys` 同发）。 */
  (e: 'expand', keys: TreeKey[], info: TreeExpandEventInfo): void;
  /** 勾选（与 `update:checkedKeys` 同发；返回值形态随 checkStrictly）。 */
  (e: 'check', checked: SafeKey[] | TreeCheckedKeys, info: TreeCheckInfo): void;
  /** 选中（与 `update:selectedKeys` 同发）。 */
  (e: 'select', keys: TreeKey[], info: TreeSelectEventInfo): void;
  /** 异步加载完成（与 `update:loadedKeys` 同发）。 */
  (e: 'load', keys: SafeKey[], info: TreeLoadEventInfo): void;
  (e: 'click', evt: MouseEvent, node: EventDataNode): void;
  (e: 'doubleClick', evt: MouseEvent, node: EventDataNode): void;
  (e: 'contextmenu', evt: MouseEvent, node: EventDataNode): void;
  (e: 'mouseEnter', evt: MouseEvent, node: EventDataNode): void;
  (e: 'mouseLeave', evt: MouseEvent, node: EventDataNode): void;
  (e: 'dragStart', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragEnter', evt: DragEvent, info: TreeDragEnterEventInfo): void;
  (e: 'dragOver', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragLeave', evt: DragEvent, info: TreeDragEventInfo): void;
  (e: 'dragEnd', evt: DragEvent, info: { node: EventDataNode | null }): void;
  (e: 'drop', evt: DragEvent, info: TreeDropEventInfo): void;
}

// ---------------------------------------------------------------------------
// Slots
// ---------------------------------------------------------------------------

export interface TreeSlotScope<TreeDataType extends object = Record<string, unknown>> {
  node: EventDataNode;
  data: TreeDataType;
}

export interface TreeSlots<TreeDataType extends object = Record<string, unknown>> {
  /** Slot presence takes priority, including an intentionally empty result. */
  title?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  icon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  switcherIcon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
  switcherLoadingIcon?: (props: TreeSlotScope<TreeDataType>) => VNodeChild;
}

// ---------------------------------------------------------------------------
// Expose（rc class 实例的公开方法面）
// ---------------------------------------------------------------------------

export interface TreeRef<TreeDataType extends object = DataNode> {
  /** 滚动到指定节点；`autoExpand: true` 时先展开再滚。 */
  scrollTo: (scroll?: number | TreeScrollConfig | null) => void;
  /** 聚焦树容器（rc focusable 管理）。 */
  focus: () => void;
  /** 节点数据实体表（只读快照）。 */
  keyEntities: Record<SafeKey, TreeDataEntity<TreeDataType>>;
}

// ---------------------------------------------------------------------------
// DirectoryTree
// ---------------------------------------------------------------------------

/**
 * DirectoryTree 的 props：与 TreeProps 相同，但**默认值不同**（G1 §4）——
 * `showIcon=true` / `expandAction='click'` / `blockNode=true` / `defaultExpandParent=true`
 * + shift/ctrl 范围多选 + File/Folder 图标。类型上直接复用 {@link TreeProps}。
 */
export type DirectoryTreeProps = TreeProps;
```

### ../../_internal/tree/types.ts

```ts
/**
 * Tree 数据模型的**共享类型**。
 *
 * ── 为什么这份类型不在 `packages/ui/src/tree/interface.ts` 里 ──────────────────
 *
 * 裁决 `early-extract-table-core-tree-core` = **C**（2026-10-07 用户裁决）：
 * `tree` 的纯逻辑（键实体表 / 勾选传导 / 数组增删）有 **≥2 个消费者**
 * （`tree-select` 与 `table`），按本仓「共享工具必须放 `src/_internal/`」的准则
 * 该搬出组件目录。
 *
 * 但那些逻辑**依赖这份数据模型** —— 只搬函数、把类型留在 `tree/interface.ts`，
 * 就会造出 `_internal/ → tree/` 的**反向依赖**，比原来的「组件间互 import」更糟。
 * ⇒ 所以**类型跟着逻辑一起搬**。
 *
 * `tree/interface.ts` 会把它们原样再导出
 * （`export type { … } from '../_internal/tree/types'`）
 * ⇒ 公开 API 面与所有既有的 `tree/interface` 导入站点**都不受影响**。
 *
 * 契约来源：antd 6.6.4 `es/tree/Tree.d.ts` + `@rc-component/tree` 1.4.0 的
 * `Tree.d.ts` / `interface.d.ts`。分析见 `docs/analysis/tree.md`。
 *
 * ⚠️ 禁止 any / as any / @ts-expect-error（H10）。
 */

import type { CSSProperties, VNodeChild } from 'vue';

/** `React.Key` 的 Vue 对应物；`SafeKey` 排除 bigint（rc :88-95 的既有约束）。 */
export type TreeKey = string | number;
export type SafeKey = Exclude<TreeKey, bigint>;

/** rc `FieldDataNode`：用户数据节点 + 递归 children（字段名可由 fieldNames 改写）。 */
export interface BasicDataNode {
  checkable?: boolean;
  disabled?: boolean;
  disableCheckbox?: boolean;
  icon?: TreeIconType;
  isLeaf?: boolean;
  selectable?: boolean;
  switcherIcon?: TreeIconType;
  className?: string;
  style?: CSSProperties;
}

export type FieldDataNode<T, ChildFieldName extends string = 'children'> = BasicDataNode &
  T &
  Partial<Record<ChildFieldName, FieldDataNode<T, ChildFieldName>[]>>;

/** rc `DataNode`（默认字段名形态）。 */
export type DataNode = FieldDataNode<{
  key: TreeKey;
  title?: VNodeChild | ((data: DataNode) => VNodeChild);
}>;

/** rc `EventDataNode`：事件回调里的节点（数据 + 运行时态）。 */
export type EventDataNode<TreeDataType extends BasicDataNode = DataNode> = {
  key: TreeKey;
  expanded: boolean;
  selected: boolean;
  checked: boolean;
  loaded: boolean;
  loading: boolean;
  halfChecked: boolean;
  dragOver: boolean;
  dragOverGapTop: boolean;
  dragOverGapBottom: boolean;
  pos: string;
  active: boolean;
} & TreeDataType &
  BasicDataNode;

/** rc `FieldNames`（`_title` 仅 tree-select 内部使用，保留字段不公开）。 */
export interface TreeFieldNames {
  title?: string;
  key?: string;
  children?: string;
}

/** rc `DataEntity`（键实体表值；keyEntities 的公开形态）。 */
export interface TreeDataEntity<TreeDataType extends object = DataNode> {
  index: number;
  key: SafeKey;
  pos: string;
  level: number;
  node: TreeDataType;
  nodes: TreeDataType[];
  children?: TreeDataEntity<TreeDataType>[];
  parent?: TreeDataEntity<TreeDataType>;
}

/** 节点态传给 icon/switcherIcon fn 的参数（rc `TreeNodeProps` 的只读子集）。 */
export interface TreeNodeRenderInfo<TreeDataType extends object = Record<string, unknown>> {
  eventKey?: TreeKey;
  expanded?: boolean;
  selected?: boolean;
  checked?: boolean;
  loaded?: boolean;
  loading?: boolean;
  halfChecked?: boolean;
  dragOver?: boolean;
  dragOverGapTop?: boolean;
  dragOverGapBottom?: boolean;
  pos?: string;
  data?: TreeDataType;
  isLeaf?: boolean;
  checkable?: boolean;
  selectable?: boolean;
  disabled?: boolean;
  disableCheckbox?: boolean;
  /** 展开函数等注入位与 rc 的 treeNodeProps 同构。 */
  [key: string]: unknown;
}

/** rc `IconType`：VNode 或按节点态求值的 fn。 */
export type TreeIconType<TreeDataType extends object = Record<string, unknown>> =
  | VNodeChild
  | ((props: TreeNodeRenderInfo<TreeDataType>) => VNodeChild);

/** rc `ExpandAction`。 */
export type TreeExpandAction = false | 'click' | 'doubleClick';

/** rc `DraggableFn` / `DraggableConfig`。 */
export type TreeNodeDraggableFn = (node: DataNode) => boolean;
export interface TreeDraggableConfig {
  /** `false` 显式关闭拖拽把手（默认渲染 HolderOutlined）。 */
  icon?: VNodeChild | false;
  nodeDraggable?: TreeNodeDraggableFn;
}
export type TreeDraggable = TreeNodeDraggableFn | boolean | TreeDraggableConfig;
```

---

# TreeSelect

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/tree-select


# TreeSelect 树选择

含多层级结构的数据（部门、地区、分类）以下拉树的形式选择，支持单选、多选、勾选级联、搜索过滤、异步加载与虚拟滚动。

## 何时使用

- 需要在**有限空间**内展示树形选择（区别于整页铺开的 `Tree`）；
- 分层级的单选 / 多选（`multiple`）或勾选（`treeCheckable`）场景；
- 大数据量时开启虚拟滚动。

## 引入

```ts
import { TreeSelect, SHOW_ALL, SHOW_PARENT, SHOW_CHILD } from '@apollo-design/ui';
```

## 代码演示































## API

### Props 与模型

`value`、`open`、`searchValue`、`treeExpandedKeys`、`treeLoadedKeys` 分别支持对应的 `v-model:<name>`。受控请求由父级接受后生效；拒绝请求保持已接受值，撤除控制沿用最后接受值。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value / defaultValue | 单选值；多选为数组。labelInValue 时为带 value/label 的对象 | TreeSelectValue | - |
| treeData | 节点数据，value 同时充当树 key；支持响应式替换与自定义字段 | TreeSelectDataNode[] | [] |
| multiple / treeCheckable | 多选 / 级联勾选；treeCheckable 自动多选 | boolean | false |
| treeCheckStrictly | 父子独立勾选，启用 labelInValue，保留 halfChecked 元数据 | boolean | false |
| labelInValue | 返回 value/label 对象 | boolean | false |
| showCheckedStrategy | 展示及通知值裁剪策略 | SHOW_ALL / SHOW_PARENT / SHOW_CHILD | 勾选时 SHOW_CHILD，否则 SHOW_ALL |
| maxCount | 最多选中数；SHOW_PARENT 或非严格 SHOW_ALL 时忽略 | number | - |
| fieldNames | value / label / children 字段映射 | TreeSelectFieldNames | - |
| treeDataSimpleMode | 按 id/pId 将平铺数据转为树；可配置 id/pId/rootPId | boolean / SimpleModeConfig | false |
| loadData | 展开时加载节点的业务服务；搜索期间不调用 | (node: TreeSelectDataNode) => Promise<unknown> | - |
| treeExpandedKeys / treeDefaultExpandedKeys | 受控 / 默认展开键 | (string / number)[] | - |
| treeLoadedKeys | 已加载键 | (string / number)[] | - |
| treeDefaultExpandAll | 默认展开全部 | boolean | false |
| treeExpandAction | 点击内容触发展开 | false / 'click' / 'doubleClick' | false |
| treeLine | 连接线，可设置 showLeafIcon | boolean / object | false |
| treeIcon / showTreeIcon | 显示节点数据中的 icon；showTreeIcon 优先 | boolean | false |
| switcherIcon | 静态展开图标；需要节点状态时使用插槽 | VNodeChild | - |
| showSearch | 是否可搜索；对象仅包含过滤及自动清空配置 | boolean / SearchConfig | false |
| searchValue | 搜索词 | string | '' |
| autoClearSearchValue | 选中后清空搜索；showSearch 对象中的同名配置优先 | boolean | true |
| filterTreeNode / treeNodeFilterProp | 过滤算法 / 匹配字段；showSearch 对象中的同名配置优先 | boolean / (input, node) => boolean；string | 默认匹配 value |
| treeNodeLabelProp | 选中标签读取字段 | string | title / label |
| placeholder / notFoundContent | 占位 / 空态内容；对应插槽优先，包括空内容及 0 | VNodeChild | - |
| allowClear | 清除按钮，可配置 clearIcon/label | boolean / object | false |
| suffixIcon / clearIcon / removeIcon | 静态图标；对应插槽优先 | VNodeChild | - |
| maxTagCount / maxTagTextLength | 标签数量 / 文字长度限制 | number | - |
| maxTagPlaceholder | 静态溢出标签；需要省略项数据时使用插槽 | VNodeChild | - |
| disabled / loading / size / status / variant | 禁用、加载、尺寸、校验状态与外观；继承当前 Provider/Form/Compact 配置 | boolean / boolean / SizeType / SelectStatus / SelectVariant | - |
| bordered | 旧边框开关，优先使用 variant | boolean | - |
| open / defaultOpen | 受控 / 默认打开 | boolean | false |
| placement / direction | 浮层位置 / 方向，局部优先，继承当前 Provider | SelectCommonPlacement / 'ltr' / 'rtl' | bottomLeft / ltr |
| getPopupContainer | 挂载容器，局部优先，继承当前 Provider | (trigger) => HTMLElement / ShadowRoot | document.body |
| popupMatchSelectWidth | 浮层宽度跟随；false 同时关闭虚拟滚动 | boolean / number | true |
| dropdownMatchSelectWidth | popupMatchSelectWidth 的旧别名 | boolean / number | - |
| popupClassName / dropdownClassName / popupStyle | 浮层旧样式通道；优先使用语义 popup.root | string / string / CSSProperties | - |
| listHeight / listItemHeight / virtual | 列表高度 / 虚拟行高 / 虚拟滚动；行高默认随当前 Tree Token 派生 | number / number / boolean | 256 / 28 / true |
| classNames / styles | 语义 class/style；可用 ({ props }) => 对象，读取当前 TreeSelectProps | TreeSelectSemanticClassNames / TreeSelectSemanticStyles 或函数 | - |
| id / tabIndex / autoFocus / maxLength | 原生输入身份、焦点与输入限制 | string / number / boolean / number | - |

原生 `class`/`style` 在渲染时落到触发器一次，支持字符串、数组、对象及撤除；`aria-label`/`aria-labelledby` 落到实际 combobox 输入。其它原生属性与监听器按 BaseSelect 的实际根契约转发。默认插槽使用一个按钮或可转发原生属性的组件作为自定义触发器。

### Emits

| 事件 | 载荷 |
| --- | --- |
| change / update:value | change(value, labels, extra)；update:value(value)。labels 在 labelInValue 下为 null。extra 包含 preValue / triggerValue / checked 或 selected |
| select / deselect | (value, node)：原始值与数据节点 |
| openChange / update:open | (open: boolean) |
| search / update:searchValue | (text: string)；search 通知输入操作，自动清空仅更新模型 |
| treeExpand / update:treeExpandedKeys | (keys) |
| treeLoad / update:treeLoadedKeys | (keys) |
| clear | 无载荷 |
| popupScroll / focus / blur / inputKeyDown | 原生 Event / FocusEvent / FocusEvent / KeyboardEvent |

`extra.triggerNode`/`allCheckedNodes` 保留历史数据节点 getter 及废弃告警。监听 change 与否不会改变模型值形状。旧 open 通知别名不再提供，统一使用 `@open-change`。

### Slots

| 插槽 | 作用域 |
| --- | --- |
| default | 单一自定义触发器 |
| treeTitleRender | { node: TreeSelectDataNode }；同时用于树标题和已选标签 |
| treeIcon / switcherIcon / switcherLoadingIcon | { node, data }；node 带当前展开/勾选/加载态，data 为原始数据 |
| tagRender | { label, value, disabled, closable, onClose, isMaxTag } |
| popupRender | { menu } |
| maxTagPlaceholder | { omittedValues } |
| suffixIcon | { searchValue, open, focused, showSearch, loading } |
| prefix / placeholder / notFoundContent / clearIcon / removeIcon / loadingIcon | 无作用域 |

插槽在渲染时读取，存在即优先，可返回空内容或 0。开发期直接迁移 `treeTitleRender`、`tagRender`、`popupRender`/`dropdownRender` 函数 prop 到同职责插槽；`switcherIcon` 函数改用 `#switcherIcon`。无函数兼容层与弃用期。节点数据中的 title/icon 函数、过滤函数及异步 loadData 保留其业务职责。

### Expose

`TreeSelectRef` 提供 `focus(options?: FocusOptions)`、`blur()`、`scrollTo(number | { key, align?, offset?, autoExpand? } | null)` 及只读的当前 `nativeElement: HTMLElement | null`。`nativeElement` 是元素属性，替代旧的方法形态。

### Provider 与主题

展示配置读取当前 `components.treeSelect`，支持 className/style、classNames/styles、showSearch/allowClear 及静态图标；替换和撤除均生效。全局方向、容器、尺寸、禁用、variant 和虚拟设置按各自职责继承。

无独立 TreeSelect Component Token 入口。树节点沿用当前 `components.Tree` 的九个 Token；外壳沿用当前 `components.Select` Token，变量同步到触发器和真实浮层。`listItemHeight` 显式值优先，否则随 Tree 的 titleHeight 及 padding 派生。浮层层级保留父 context 规则，显式 popup.root/popupStyle zIndex 优先并保留 0。

### 静态属性

`TreeSelect.SHOW_ALL` / `SHOW_PARENT` / `SHOW_CHILD` 与具名导出等价。`TreeSelect.TreeNode` children 数据形式不提供。


## 组件 Token (component-token)

TreeSelect 复用 Tree 的组件 Token，通过浮层语义类覆盖 `--apollo-tree-node-selected-bg`、`--apollo-tree-title-height` 等变量即可切换节点配色与行高。

### component-token.vue

```vue
<script setup lang="ts">
import type { TreeSelectDataNode, TreeSelectValue } from '@apollo-design/ui';
import { Select, Space, Tag, TreeSelect } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const presets = [
  {
    value: 'default',
    label: '默认蓝',
    selectedBg: '#e6f4ff',
    selectedColor: '#1677ff',
    hoverBg: 'rgba(22, 119, 255, 0.08)',
    titleHeight: '24px',
  },
  {
    value: 'purple',
    label: '紫罗兰',
    selectedBg: '#f9f0ff',
    selectedColor: '#722ed1',
    hoverBg: 'rgba(114, 46, 209, 0.08)',
    titleHeight: '30px',
  },
  {
    value: 'green',
    label: '青绿色',
    selectedBg: '#f6ffed',
    selectedColor: '#389e0d',
    hoverBg: 'rgba(56, 158, 13, 0.08)',
    titleHeight: '36px',
  },
];

type PresetValue = (typeof presets)[number]['value'];

const preset = ref<PresetValue>('default');
const value = ref<TreeSelectValue>('leaf-1-1');

const currentPreset = computed(
  () =>
    presets.find((item) => item.value === preset.value) ?? (presets[0] as (typeof presets)[number]),
);

const popupStyle = computed(() => ({
  '--tree-select-demo-selected-bg': currentPreset.value.selectedBg,
  '--tree-select-demo-selected-color': currentPreset.value.selectedColor,
  '--tree-select-demo-hover-bg': currentPreset.value.hoverBg,
  '--tree-select-demo-title-height': currentPreset.value.titleHeight,
}));

const treeData: TreeSelectDataNode[] = [
  {
    title: '研发中心',
    value: 'engineering',
    children: [
      {
        title: '前端组',
        value: 'frontend',
        children: [
          { title: '组件库', value: 'leaf-1-1' },
          { title: '文档站', value: 'leaf-1-2' },
        ],
      },
      { title: '后端组', value: 'backend' },
    ],
  },
  {
    title: '设计中心',
    value: 'design',
    children: [
      { title: '视觉组', value: 'visual' },
      { title: '交互组', value: 'interaction' },
    ],
  },
];

function onPresetChange(next: unknown): void {
  preset.value = next as PresetValue;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>树节点 Token</span>
      <Select aria-label="Tree node theme"
        :value="preset"
        :options="presets"
        style="width: 140px"
        @change="onPresetChange"
      />
      <Tag color="blue">titleHeight: {{ currentPreset.titleHeight }}</Tag>
      <Tag>选中背景: {{ currentPreset.selectedBg }}</Tag>
    </Space>

    <TreeSelect aria-label="Tree select: component token"
      v-model:value="value"
      :tree-data="treeData"
      :popup-style="popupStyle"
      :class-names="{ popup: { root: 'tree-select-token-demo-popup' } }"
      tree-default-expand-all
      placeholder="打开下拉查看节点样式"
      style="width: 280px; max-width: 100%"
    />
  </div>
</template>

<style>
.tree-select-token-demo-popup .apollo-tree-select {
  --apollo-tree-node-selected-bg: var(--tree-select-demo-selected-bg, #e6f4ff);
  --apollo-tree-node-selected-color: var(--tree-select-demo-selected-color, #1677ff);
  --apollo-tree-node-hover-bg: var(--tree-select-demo-hover-bg, rgba(0, 0, 0, 0.04));
  --apollo-tree-title-height: var(--tree-select-demo-title-height, 24px);
  --apollo-tree-switcher-size: var(--tree-select-demo-title-height, 24px);
  --apollo-tree-indent-size: var(--tree-select-demo-title-height, 24px);
}
</style>
```

## 浮层方位 (placement)

使用 `placement` 控制下拉浮层相对选择框的位置，按钮与 `v-model:open` 可保持浮层打开以实时对比四个方位。

### placement.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { Button, Select, Space, Tag, TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

type Placement = 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight';

const placement = ref<Placement>('bottomLeft');
const open = ref(false);
const value = ref<TreeSelectValue>();

const placementOptions: { value: Placement; label: string }[] = [
  { value: 'bottomLeft', label: 'bottomLeft' },
  { value: 'bottomRight', label: 'bottomRight' },
  { value: 'topLeft', label: 'topLeft' },
  { value: 'topRight', label: 'topRight' },
];

const treeData = [
  {
    title: '研发中心',
    value: 'engineering',
    children: [
      { title: '前端组', value: 'frontend' },
      { title: '后端组', value: 'backend' },
    ],
  },
  {
    title: '设计中心',
    value: 'design',
    children: [
      { title: '视觉组', value: 'visual' },
      { title: '交互组', value: 'interaction' },
    ],
  },
];

function onPlacementChange(next: unknown): void {
  placement.value = next as Placement;
}
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <span>placement</span>
      <Select aria-label="Popup placement"
        :value="placement"
        :options="placementOptions"
        style="width: 160px"
        @change="onPlacementChange"
      />
      <Button @click="open = true">打开浮层</Button>
      <Button @click="open = false">关闭浮层</Button>
      <Tag color="blue">{{ placement }}</Tag>
      <Tag>{{ open ? '浮层已打开' : '浮层已关闭' }}</Tag>
    </Space>

    <TreeSelect aria-label="Tree select: placement"
      v-model:value="value"
      v-model:open="open"
      :placement="placement"
      :tree-data="treeData"
      tree-default-expand-all
      placeholder="切换浮层方位"
      style="width: 280px; max-width: 100%"
    />
  </div>
</template>
```

## 值包含标签 (label-in-value)

开启 `labelInValue` 后，选择结果会以 `{ value, label }` 形式返回，下方标签会同时展示 value 与 label。

### label-in-value.vue

```vue
<script setup lang="ts">
import type { TreeSelectDataNode, TreeSelectValue } from '@apollo-design/ui';
import { Space, Tag, TreeSelect } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const value = ref<TreeSelectValue>({
  value: 'leaf-1-1',
  label: '组件库',
});

const treeData: TreeSelectDataNode[] = [
  {
    title: '研发中心',
    value: 'engineering',
    children: [
      {
        title: '前端组',
        value: 'frontend',
        children: [
          { title: '组件库', value: 'leaf-1-1' },
          { title: '文档站', value: 'leaf-1-2' },
        ],
      },
      { title: '后端组', value: 'backend' },
    ],
  },
];

const selectedInfo = computed(() => {
  const current = value.value;
  if (!current || typeof current !== 'object' || Array.isArray(current)) return '未选择';
  return `value: ${String(current.value)} · label: ${String(current.label)}`;
});
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Tag color="blue">{{ selectedInfo }}</Tag>
      <Tag>labelInValue 会同时保留 value 与展示文案</Tag>
    </Space>

    <TreeSelect aria-label="Tree select: label in value"
      v-model:value="value"
      :tree-data="treeData"
      label-in-value
      tree-default-expand-all
      allow-clear
      placeholder="请选择节点"
      style="width: 280px; max-width: 100%"
    />
  </div>
</template>
```

## 默认展开全部 (tree-default-expand-all)

使用 `treeDefaultExpandAll` 让多层级树在首次打开时展开所有父节点，便于直接浏览与选择深层节点。

### tree-default-expand-all.vue

```vue
<script setup lang="ts">
import type { TreeSelectDataNode, TreeSelectValue } from '@apollo-design/ui';
import { Space, Tag, TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>('leaf-1-1-1');

const treeData: TreeSelectDataNode[] = [
  {
    title: '研发中心',
    value: 'engineering',
    children: [
      {
        title: '前端组',
        value: 'frontend',
        children: [
          {
            title: '组件库',
            value: 'components',
            children: [
              { title: 'Button', value: 'leaf-1-1-1' },
              { title: 'Table', value: 'leaf-1-1-2' },
            ],
          },
          { title: '文档站', value: 'docs' },
        ],
      },
      { title: '后端组', value: 'backend' },
    ],
  },
  {
    title: '设计中心',
    value: 'design',
    children: [
      { title: '视觉组', value: 'visual' },
      { title: '交互组', value: 'interaction' },
    ],
  },
];
</script>

<template>
  <div>
    <Space :size="12" wrap style="margin-bottom: 16px">
      <Tag color="blue">treeDefaultExpandAll</Tag>
      <Tag>打开下拉后所有父节点默认展开</Tag>
    </Space>

    <TreeSelect aria-label="Tree select: tree default expand all"
      v-model:value="value"
      :tree-data="treeData"
      tree-default-expand-all
      placeholder="所有节点默认展开"
      style="width: 280px; max-width: 100%"
    />
  </div>
</template>
```

## async (async)

异步加载（`loadData`），展开时加载子节点。

### async.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect, type TreeSelectDataNode } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>();
const treeData = ref<TreeSelectDataNode[]>([{ title: 'Expand to load', value: '0' }]);

const onLoadData = (treeNode: TreeSelectDataNode) =>
  new Promise<void>((resolve) => {
    if (treeNode.children) {
      resolve();
      return;
    }
    setTimeout(() => {
      treeData.value = [
        {
          title: 'Expand to load',
          value: '0',
          children: [{ title: 'Child Node', value: `${treeNode.value}-0`, isLeaf: true }],
        },
      ];
      resolve();
    }, 500);
  });
</script>

<template>
  <TreeSelect aria-label="Tree select: async" v-model:value="value" :load-data="onLoadData" :tree-data="treeData" placeholder="请选择" />
</template>
```

## basic (basic)

最简单的用法（`v-model:value` 绑定）。

### basic.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>();
const search = ref('');
const open = ref(false);

const treeData = [
  {
    title: 'parent 1',
    value: '0-0',
    children: [
      { title: 'leaf 1', value: '0-0-0' },
      { title: 'leaf 2', value: '0-0-1' },
    ],
  },
  { title: 'parent 2', value: '0-1' },
];
</script>

<template>
  <TreeSelect aria-label="Tree select: basic" v-model:value="value" v-model:search-value="search" v-model:open="open" show-search :tree-data="treeData" placeholder="请选择" />
</template>
```

## check-strictly (check-strictly)

勾选完全受控（`treeCheckStrictly`）：父子不关联，`value` 为 LabeledValue（含 halfChecked）。

### check-strictly.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>([{ value: '0-0-0', label: 'leaf 1', halfChecked: false }]);

const treeData = [
  {
    title: 'parent 1',
    value: '0-0',
    children: [
      { title: 'leaf 1', value: '0-0-0' },
      { title: 'leaf 2', value: '0-0-1' },
    ],
  },
];
</script>

<template>
  <TreeSelect aria-label="Tree select: check strictly" v-model:value="value" tree-checkable tree-check-strictly show-search :tree-data="treeData" placeholder="请选择" />
</template>
```

## disabled (disabled)

禁用：整树（`disabled`）或节点级（data 的 `disabled`）。

### disabled.vue

```vue
<script setup lang="ts">
import { TreeSelect } from '@apollo-design/ui';

const treeData = [
  { title: 'parent', value: '0-0', disabled: true, children: [{ title: 'leaf', value: '0-0-0' }] },
  { title: 'ok', value: '0-1' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; row-gap: 12px">
    <TreeSelect aria-label="Tree select: disabled" :tree-data="treeData" placeholder="节点级 disabled" />
    <TreeSelect aria-label="Tree select: disabled" :tree-data="treeData" disabled placeholder="整树 disabled" />
  </div>
</template>
```

## field-names (field-names)

自定义字段名（`fieldNames`）：`value` 字段同时充当树的 key。

### field-names.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>();

const treeData = [
  {
    name: 'parent',
    id: '0-0',
    subs: [{ name: 'leaf', id: '0-0-0' }],
  },
];
</script>

<template>
  <TreeSelect aria-label="Tree select: field names"
    v-model:value="value"
    :tree-data="treeData"
    :field-names="{ value: 'id', label: 'name', children: 'subs' }"
    placeholder="自定义字段名"
  />
</template>
```

## max-count (max-count)

限制最大选中数量（`maxCount`，多选 / SHOW_CHILD 下生效）。

### max-count.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>(['0-0-0']);

const treeData = [
  {
    title: 'parent 1',
    value: '0-0',
    children: [
      { title: 'leaf 1', value: '0-0-0' },
      { title: 'leaf 2', value: '0-0-1' },
    ],
  },
];
</script>

<template>
  <TreeSelect aria-label="Tree select: max count" v-model:value="value" multiple :max-count="2" :tree-data="treeData" placeholder="最多选 2 个" />
</template>
```

## multiple (multiple)

多选与标签（`multiple`），`allowClear` 一键清空。

### multiple.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>(['0-0-0']);

const treeData = [
  {
    title: 'parent 1',
    value: '0-0',
    children: [
      { title: 'leaf 1', value: '0-0-0' },
      { title: 'leaf 2', value: '0-0-1' },
    ],
  },
  { title: 'parent 2', value: '0-1' },
];
</script>

<template>
  <TreeSelect aria-label="Tree select: multiple" v-model:value="value" multiple :tree-data="treeData" placeholder="请选择" allow-clear />
</template>
```

## placeholder-slot (placeholder-slot)

placeholder 插槽自定义。

### placeholder-slot.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>();
const treeData = [{ title: 'leaf', value: '0-0-0' }];
</script>

<template>
  <TreeSelect aria-label="Tree select: placeholder slot" v-model:value="value" :tree-data="treeData">
    <template #treeTitleRender="{ node }"><span>{{ node.title }}</span></template>
    <template #placeholder>
      <span style="color: #bfbfbf">自定义 placeholder</span>
    </template>
  </TreeSelect>
</template>
```

## show-checked-strategy (show-checked-strategy)

展示策略（`showCheckedStrategy`）：`SHOW_PARENT` 回显父节点 / `SHOW_ALL` 全量回显。

### show-checked-strategy.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>(['0-0-0', '0-0-1']);

const treeData = [
  {
    title: 'parent 1',
    value: '0-0',
    children: [
      { title: 'leaf 1', value: '0-0-0' },
      { title: 'leaf 2', value: '0-0-1' },
    ],
  },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; row-gap: 12px">
    <TreeSelect aria-label="Tree select: show checked strategy" v-model:value="value" tree-checkable show-checked-strategy="SHOW_PARENT" :tree-data="treeData" placeholder="SHOW_PARENT" />
    <TreeSelect aria-label="Tree select: show checked strategy" v-model:value="value" tree-checkable show-checked-strategy="SHOW_ALL" :tree-data="treeData" placeholder="SHOW_ALL" />
  </div>
</template>
```

## simple-mode (simple-mode)

平铺数据建树（`treeDataSimpleMode`，id/pId 结构）。

### simple-mode.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>();

const treeData = [
  { id: 'p1', value: 'p1', title: 'Parent 1', pId: '' },
  { id: 'c1', value: 'c1', title: 'Child 1', pId: 'p1' },
];
</script>

<template>
  <TreeSelect aria-label="Tree select: simple mode" v-model:value="value" tree-data-simple-mode :tree-data="treeData" placeholder="simple mode" />
</template>
```

## size (size)

三种尺寸（`size`）。

### size.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>();
const treeData = [{ title: 'leaf', value: '0-0-0' }];
</script>

<template>
  <div style="display: flex; flex-direction: column; row-gap: 12px">
    <TreeSelect aria-label="Tree select: size" v-model:value="value" size="large" :tree-data="treeData" placeholder="large" />
    <TreeSelect aria-label="Tree select: size" v-model:value="value" :tree-data="treeData" placeholder="middle" />
    <TreeSelect aria-label="Tree select: size" v-model:value="value" size="small" :tree-data="treeData" placeholder="small" />
  </div>
</template>
```

## status (status)

校验状态（`status`）：error / warning。

### status.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>();

const treeData = [{ title: 'parent', value: '0-0', children: [{ title: 'leaf', value: '0-0-0' }] }];
</script>

<template>
  <div style="display: flex; flex-direction: column; row-gap: 12px">
    <TreeSelect aria-label="Tree select: status" v-model:value="value" status="error" :tree-data="treeData" placeholder="error" />
    <TreeSelect aria-label="Tree select: status" v-model:value="value" status="warning" :tree-data="treeData" placeholder="warning" />
  </div>
</template>
```

## tree-checkable (tree-checkable)

勾选模式（`treeCheckable`），父子级联勾选，默认 `SHOW_CHILD` 策略展示。

### tree-checkable.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>(['0-0-0']);

const treeData = [
  {
    title: 'parent 1',
    value: '0-0',
    children: [
      { title: 'leaf 1', value: '0-0-0' },
      { title: 'leaf 2', value: '0-0-1' },
    ],
  },
  { title: 'parent 2', value: '0-1' },
];
</script>

<template>
  <TreeSelect aria-label="Tree select: tree checkable" v-model:value="value" tree-checkable show-search :tree-data="treeData" placeholder="请选择" />
</template>
```

## tree-line (tree-line)

下拉树带连接线（`treeLine`）。

### tree-line.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>();
const treeData = [
  {
    title: 'parent 1',
    value: '0-0',
    children: [{ title: 'leaf 1', value: '0-0-0' }],
  },
];
</script>

<template>
  <TreeSelect aria-label="Tree select: tree line" v-model:value="value" :tree-line="true" :tree-data="treeData" placeholder="连接线" />
</template>
```

## virtual-scroll (virtual-scroll)

大量节点下虚拟滚动（`listHeight` 控制浮层高度）。

### virtual-scroll.vue

```vue
<script setup lang="ts">
import type { TreeSelectValue } from '@apollo-design/ui';
import { TreeSelect, type TreeSelectDataNode } from '@apollo-design/ui';
import { ref } from 'vue';

const value = ref<TreeSelectValue>();

const build = (pre: string, level: number): TreeSelectDataNode[] | undefined => {
  if (level < 0) return undefined;
  return [0, 1].map((i) => {
    const v = `${pre}${i}`;
    return { title: `节点 ${v}`, value: v, children: build(`${v}-`, level - 1) };
  });
};
const treeData: TreeSelectDataNode[] = build('0-', 3) ?? [];
</script>

<template>
  <TreeSelect aria-label="Tree select: virtual scroll" v-model:value="value" :tree-data="treeData" tree-default-expand-all :list-height="200" placeholder="虚拟滚动" />
</template>
```

---

# Typography

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/typography


标题、段落、行内文本和链接，支持复制、编辑及省略。

## 代码演示

14 个示例覆盖基础排版、五级标题、语义色、复制、编辑、受控省略、中间省略、后缀、组件 Token、语义样式和 Table 消费场景。

## API

```ts
import { Typography, Text, Title, Paragraph, Link } from '@apollo-design/ui';
import '@apollo-design/ui/style.css';
```

具名组件与 `Typography.Text / Title / Paragraph / Link` 是同一组件。按需样式入口为 `@apollo-design/ui/typography/style.css`；应用仍需加载主题及基础样式。

### 组件与内容

| 组件 | 根元素 | 能力 |
|---|---|---|
| Typography | `article`；可用 `component` 指定标签 | 排版容器、语义样式 |
| Text | `span` | 装饰、复制、编辑、单行省略 |
| Title | `h1`…`h5` | 装饰、复制、编辑、省略；`level` 默认 1 |
| Paragraph | `div` | 装饰、复制、编辑、多行省略 |
| Link | `span` 外壳，内含原生 `a` | 原生链接及装饰、复制、编辑、布尔省略 |

五个组件均使用默认插槽，可传文本、Fragment、条件节点、原生元素和 Vue 组件。四个固定语义组件不接受 `component`；需要自定义容器标签使用 Typography。Title 不接受 `strong`。

Link 的复制/编辑按钮是原生链接的兄弟节点，避免交互控件嵌套。`href`、`target`、`rel`、链接 ARIA、`tabindex` 和原生事件作用于 `a`；`id`、`class`、`style` 和 expose 作用于外壳。`target="_blank"` 且未指定 `rel` 时补 `noopener noreferrer`。禁用链接设置 `aria-disabled`、退出 Tab 顺序并阻止激活。

### 公共 Props 与原生 attrs

| 参数 | 类型 / 默认值 | 说明 |
|---|---|---|
| prefixCls | `string` | 当前 ConfigProvider 前缀，默认 `apollo-typography` |
| direction | `'ltr' \| 'rtl'` | 默认使用当前 Provider |
| classNames | 对象或 `({ props }) => 对象` | `root / actions / action / textarea` 类名 |
| styles | 对象或 `({ props }) => 对象` | 同名语义节点的 Vue CSSProperties |
| component | `string`，默认 `article` | 仅 Typography |

根 `class` / `style` / `id` / `data-*` 使用 Vue 原生 attrs；支持动态替换及移除。类名合并，原生 style 覆盖 `styles.root`。语义函数的 `props` 为 `BaseTypographyProps`。ConfigProvider 的 `components.typography` 可提供类名、样式及语义配置；配置替换、函数式配置及移除不重建业务插槽或正在编辑的输入框。

### Text / Title / Paragraph / Link

| 参数 | 类型 / 默认值 | 说明 |
|---|---|---|
| type | `'secondary' \| 'success' \| 'warning' \| 'danger'` | 语义文字色 |
| disabled | `boolean`，false | 禁用样式；Link 同时阻止导航 |
| copyable | `boolean \| CopyConfig` | 复制 |
| editable | `boolean \| EditConfig` | 编辑 |
| ellipsis | `boolean \| EllipsisConfig` | Text 排除 rows / expandable / onExpand；Link 仅布尔 |
| strong / underline / delete / code / mark / keyboard / italic | `boolean`，false | 七种文本装饰；Title 排除 strong |
| actions | `{ placement?: 'start' \| 'end' }` | 操作区位置，默认 end |
| title | `string` | 原生标题及省略提示候选 |
| level | `1 \| 2 \| 3 \| 4 \| 5`，1 | 仅 Title |
| target / rel | `string` | 仅 Link；href 使用原生 attrs |

### CopyConfig

| 字段 | 类型 / 默认值 | 行为 |
|---|---|---|
| text | `string \| (() => string \| Promise<string>)` | 未提供时读取内容文本；空字符串会复制空文本 |
| onCopy | `(event?: MouseEvent) => void` | 实际写入成功后调用 |
| icon / tooltips | `VNodeChild \| [VNodeChild, VNodeChild]` | 长度为 2 的数组表示未复制/已复制；其他长度保留为完整节点内容 |
| format | `'text/plain' \| 'text/html'` | 剪贴板格式 |
| tabIndex | `number` | 复制按钮 Tab 顺序 |

`tooltips: false` 关闭提示。默认提示读取当前语言。一次异步复制未完成时拒绝重复请求；失败不显示复制成功，卸载后不更新状态或发送完成回调。自定义图标仍保留原生按钮和可访问名称。

### EditConfig

| 字段 | 类型 / 默认值 | 行为 |
|---|---|---|
| text | `string` | 编辑初值；未提供时使用可识别的纯文本内容 |
| editing | `boolean` | 受控编辑态；省略时为非受控 |
| onStart / onCancel / onEnd | `() => void` | 进入、取消、Enter 保存完成 |
| onChange | `(value: string) => void` | Enter 或失焦保存；首尾空白被移除，内部换行保留 |
| icon / tooltip / enterIcon | `VNodeChild` | 编辑图标、完整提示内容、确认图标；tooltip false 关闭提示，enterIcon null 隐藏 |
| triggerType | `('icon' \| 'text')[]`，`['icon']` | text 模式仍提供可聚焦的原生编辑按钮 |
| autoSize | `boolean \| { minRows?: number; maxRows?: number }`，true | 原生 textarea 高度随内容、宽度和当前配置变化 |
| maxLength / tabIndex | `number` | 编辑框长度限制 / 编辑按钮 Tab 顺序 |

编辑框填满其宿主宽度，并保留确认图标所需空间；`autoSize: false` 仍显示完整的一行。边框、背景及焦点读取当前主题，`styles.textarea` 可显式覆盖原生样式。

Enter 保存，Escape 取消；带修饰键的 Enter 保留原生换行，IME 组合期间不提交。受控模式中回调仅通知请求，父组件决定是否关闭。键盘完成后恢复所属编辑按钮焦点；失焦至外部控件时保留外部焦点。

`aria-label` / `aria-labelledby` / `aria-describedby` 传给实际 textarea。未提供名称时使用纯文本内容或当前语言的编辑文案。编辑态保留根 attrs 和实际根 expose。

### EllipsisConfig

| 字段 | 类型 / 默认值 | 行为 |
|---|---|---|
| rows | `number`，1 | 正有限值向下取整，非法值回退 1 |
| expandable | `boolean \| 'collapsible'`，false | 可展开；collapsible 支持再次收起 |
| suffix | `string` | 省略后的后缀 |
| symbol | `VNodeChild \| ((expanded: boolean) => VNodeChild)` | 展开/收起按钮内容 |
| expanded / defaultExpanded | `boolean` | 受控值 / 非受控初值 |
| onExpand | `(event: MouseEvent, info: { expanded: boolean }) => void` | 展开请求 |
| onEllipsis | `(ellipsis: boolean) => void` | 实际省略状态变化时调用 |
| tooltip | `VNodeChild \| { title?: VNodeChild }` | true 使用原内容；false 关闭 |

简单情况使用 CSS；需要操作区、后缀或展开时按实际宽度测量。隐藏测量区使用已挂载内容的原生 DOM 投影，不再次挂载业务组件。动态宽度、行数、内容和字体变化会重新测量，过期测量及卸载任务取消。

### Slots / Emits / v-model / Expose

唯一公共插槽是 `default`。没有组件 emits 或 v-model；编辑和展开通过各自配置的受控值与回调表达。`TypographyRef.nativeElement` 是只读的当前实际根元素或 null，包含编辑态；Link 返回外壳。

### 组件 Token

通过 `ConfigProvider :theme="{ components: { Typography: { titleMarginTop: 0, titleMarginBottom: '0.8em' } } }"` 设置。数字按 px 处理，支持 0、配置替换和移除。

| Token | 默认值 | 消费位置 |
|---|---|---|
| titleMarginTop | `1.2em` | 内容后标题的上间距 |
| titleMarginBottom | `0.5em` | 标题下间距 |

默认语义文字和操作文字随当前主题保持可读对比。原生 style 是用户显式覆盖；使用自定义前景色时需与背景配对。


## 基础 (basic)

`Title` / `Paragraph` / `Text` / `Link` 四件套是最常见的排版组合。

### basic.vue

```vue
<script setup lang="ts">
import { Link, Paragraph, Text, Title } from '@apollo-design/ui';
</script>

<template>
  <Title>Introduction</Title>
  <Paragraph>
    In the process of internal desktop applications development, many different design specs and
    implementations would be involved.
    <Text strong>It is a long established fact</Text>
    that a reader will be distracted by the readable content of a page when looking at its layout.
  </Paragraph>
  <Paragraph>
    <Text>Read more in </Text>
    <Link href="https://apollo.design" target="_blank">Apollo Design</Link>.
  </Paragraph>
</template>
```

## 标题组件 (title)

`level` 取 `1`~`5`，分别渲染 `h1`~`h5`。默认值是 `1`。

⚠️ 非法 `level`（例如 `6`）会**退回 `h1` 并告警** —— 这是 antd 的既定行为，
而不是「渲染成 `h6`」。

### title.vue

```vue
<script setup lang="ts">
import { Title } from '@apollo-design/ui';
</script>

<template>
  <Title :level="1">h1. Apollo Design</Title>
  <Title :level="2">h2. Apollo Design</Title>
  <Title :level="3">h3. Apollo Design</Title>
  <Title :level="4">h4. Apollo Design</Title>
  <Title :level="5">h5. Apollo Design</Title>
</template>
```

## 文本与装饰 (text)

`type` 是语义色（`secondary` / `success` / `warning` / `danger`），`disabled` 是禁用态。

七个装饰开关（`code` / `mark` / `underline` / `delete` / `strong` / `keyboard` / `italic`）
的**嵌套顺序是契约**：由内到外依次是 `strong → u → del → code → mark → kbd → i`。

### text.vue

```vue
<script setup lang="ts">
import { Text } from '@apollo-design/ui';
</script>

<template>
  <Text>Apollo Design</Text>
  <br />
  <Text type="secondary">Secondary</Text>
  <br />
  <Text type="success">Success</Text>
  <br />
  <Text type="warning">Warning</Text>
  <br />
  <Text type="danger">Danger</Text>
  <br />
  <Text disabled>Disabled</Text>
  <br />
  <Text mark>Marked text</Text>
  <br />
  <Text code>code</Text>
  <br />
  <Text keyboard>Ctrl + C</Text>
  <br />
  <Text underline>Underline</Text>
  <br />
  <Text delete>Deleted</Text>
  <br />
  <Text strong>Strong</Text>
  <br />
  <Text italic>Italic</Text>
</template>
```

## 省略号 (ellipsis)

`rows` 控制行数：`1` 走 `text-overflow`，`>1` 走 `-webkit-line-clamp`。

一旦传了 `expandable` / `suffix` / `onEllipsis`，或同时开了 `copyable` / `editable`，
CSS 省略号就**做不到**（省略号后面还要放东西），组件会改用 **JS 二分裁剪**。

⚠️ JS 裁剪依赖**真实布局测量**（`ResizeObserver` + `scrollHeight`/`clientHeight`）。
jsdom 没有布局引擎，所以 L1/L2 通过打桩尺寸驱动状态机，真实排版结果由 L6 覆盖 ——
见 `README.md` §7。

### ellipsis.vue

```vue
<script setup lang="ts">
import { Paragraph, Text } from '@apollo-design/ui';

const longText =
  'Ant Design, a design language for background applications, is refined by Ant UED Team. ' +
  'This sentence is intentionally long enough to overflow a narrow box, so the component has ' +
  'to decide where to cut it.';
</script>

<template>
  <Paragraph :ellipsis="{ rows: 1 }" :style="{ width: '220px' }">
    {{ longText }}
  </Paragraph>
  <Paragraph :ellipsis="{ rows: 2 }" :style="{ width: '220px' }">
    {{ longText }}
  </Paragraph>
  <Paragraph :ellipsis="{ rows: 2, expandable: true, suffix: '...more' }" :style="{ width: '220px' }">
    {{ longText }}
  </Paragraph>
  <Text :ellipsis="{ tooltip: 'I am a tooltip' }" :style="{ width: '220px' }">
    {{ longText }}
  </Text>
</template>
```

## 可复制 (copyable)

`copyable.text` 决定**写进剪贴板**的内容，与显示内容可以不同；它也可以是返回
`Promise<string>` 的函数（异步取文本）。

`tooltips` 与 `icon` 都支持 `[未复制, 已复制]` 二元组。传 `false` 表示**显式不渲染**
（`undefined` 才是「用默认」—— 两者语义不同）。

### copyable.vue

```vue
<script setup lang="ts">
import { Paragraph, Text } from '@apollo-design/ui';
</script>

<template>
  <Paragraph :copyable="true">Copy me to the clipboard</Paragraph>
  <Paragraph :copyable="{ text: 'Custom copy text' }">Shown text is different from copied text</Paragraph>
  <Paragraph :copyable="{ tooltips: ['Click to copy', 'Copied!'] }">Custom tooltips</Paragraph>
  <Text :copyable="true" />
</template>
```

## 可编辑 (editable)

`triggerType` 决定进入编辑态的方式：`['icon']`（默认，点铅笔图标）、`['text']`（点文字）。

编辑时 Enter 保存、Esc 取消、失焦保存，保存值会去掉首尾空格。输入法组合中，或带 Ctrl / Alt / Meta / Shift 的 Enter 不触发保存。

最后一个示例使用正常 Vue 模板的条件默认插槽。它最初没有正文；更新当前文本，再显示、编辑或复制正文，操作均读取当前内容。再次移除正文时，复制按钮恢复只有图标的状态。编辑态使用原生 `<textarea>`，示例显式提供可访问名。

### editable.vue

```vue
<script setup lang="ts">
import { Button, Text } from '@apollo-design/ui';
import { ref } from 'vue';

const editableText = ref('Click the icon to edit');
const showContent = ref(false);
const revision = ref(0);
const currentText = ref('Current template text 0');
const updateText = () => {
  revision.value++;
  currentText.value = `Current template text ${revision.value}`;
};
</script>

<template>
  <Text aria-label="Editable plain text" :editable="true">Click the icon to edit</Text>
  <br />
  <Text
    aria-label="Controlled editable text"
    :editable="{ text: editableText, onChange: (value: string) => (editableText = value) }"
  >
    {{ editableText }}
  </Text>
  <br />
  <Text aria-label="Edit by clicking text" :editable="{ triggerType: ['text'] }">Click the text to edit</Text>
  <br />
  <Text aria-label="Editable without tooltip" :editable="{ tooltip: false }">No tooltip on the edit icon</Text>
  <section data-conditional-typography>
    <p style="display: flex; flex-wrap: wrap; gap: 8px">
      <Button @mousedown.prevent @click="showContent = !showContent">Toggle editable content</Button>
      <Button @mousedown.prevent @click="updateText">Update editable text</Button>
    </p>
    <Text aria-label="Conditional editable text" copyable
      :editable="{ onChange: (value: string) => (currentText = value) }">
      <template v-if="showContent" #default>{{ currentText }}</template>
    </Text>
  </section>
</template>
```

## 语义化 classNames / styles (semantic)

四个语义槽位：`root`（根元素）、`actions`（操作区）、`action`（每个操作按钮）、`textarea`（仅编辑态的输入框）。`classNames` 拼接类名，`styles` 合并同名区域的样式。函数式配置收到 `{ props }`，其中 `prefixCls` / `direction` 是解析后的值。

保留对象式、函数式和操作区示例，最后演示 Vue 原生 `class` / `style`：动态字符串 → 混合数组 → 对象 → 移除。原生 style 优先于 `styles.root`；移除后恢复语义根样式。输入草稿和焦点随样式切换保留。

局部 ConfigProvider 示例进一步替换整个 `components.typography` 配置：对象 → 新对象 → 捕获当前普通值的新函数 → 移除。根、操作区、按钮和编辑输入的类名/样式同步更新；函数只读取既有 `props.prefixCls`，可看到解析后的前缀。原生根 style 和本地 `styles.root` 的覆盖顺序保持，输入草稿和焦点不被配置替换重置。

### semantic.vue

```vue
<script setup lang="ts">
import {
  Button,
  ConfigProvider,
  type ConfigProviderProps,
  Input,
  Paragraph,
  Text,
  type TypographyConfig,
  type TypographyProps,
} from '@apollo-design/ui';
import { computed, ref, type StyleValue } from 'vue';

/** 对象式：直接给槽位类名 / 样式。 */
const classNamesObject: TypographyProps['classNames'] = {
  root: 'demo-typography-root',
  actions: 'demo-typography-actions',
  action: 'demo-typography-action',
};

const stylesObject: TypographyProps['styles'] = {
  root: { backgroundColor: 'var(--apollo-color-fill-alter)' },
  actions: { marginInlineStart: '8px' },
};

/**
 * 函数式：`info.props` 是**合并后**的 props —— `prefixCls` 已是解析后的
 * `apollo-typography`，`direction` 也已并入 ConfigProvider 的取值。
 *
 * ⚠️ `info.props` 的类型是 `BaseTypographyProps`（= `TypographyProps`），**不含**
 *    `disabled` / `type` / `copyable` 这些 `BlockProps` 独有的字段 —— 上游 antd 也如此
 *    （`TypographySemanticAllType = GenerateSemantic<TypographySemanticType, BaseTypographyProps>`）。
 *    所以这里分支用的判据必须是基础 props 里有的（`prefixCls`）。
 */
const classNamesFn: TypographyProps['classNames'] = (info) =>
  info.props.prefixCls === 'apollo-typography-alt'
    ? { root: 'demo-typography-root--alt' }
    : { root: 'demo-typography-root' };

const phase = ref(0);
const nativeClass = computed(() =>
  phase.value < 3 ? ['native-demo-root', `native-demo-phase-${phase.value}`] : undefined,
);
const nativeStyle = computed<StyleValue>(() => {
  if (phase.value === 0)
    return 'color:var(--apollo-color-text);padding-inline-start:var(--apollo-padding-xs);--native-demo-phase:string';
  if (phase.value === 1)
    return [
      'color:var(--apollo-color-text-secondary);--native-demo-phase:array',
      {
        paddingInlineStart: 'var(--apollo-padding-sm)',
        paddingInlineEnd: 'var(--apollo-padding-xs)',
      },
    ];
  if (phase.value === 2)
    return {
      color: 'var(--apollo-color-text)',
      paddingInlineStart: 'var(--apollo-padding-md)',
      '--native-demo-phase': 'object',
    };
  return undefined;
});
const nativeSemanticStyles: TypographyProps['styles'] = {
  root: {
    color: 'var(--apollo-color-text-secondary)',
    paddingInlineStart: 'var(--apollo-padding-xxs)',
    '--semantic-demo-root': 'kept',
  },
};

const providerPhase = ref(0);
const makeProviderConfig = (phase: number): TypographyConfig => {
  const marker = phase === 0 ? 'first' : phase === 1 ? 'second' : 'function';
  const classes = {
    root: `demo-provider-root-${marker}`,
    actions: `demo-provider-actions-${marker}`,
    action: `demo-provider-action-${marker}`,
    textarea: `demo-provider-textarea-${marker}`,
  };
  const semanticStyles = {
    root: { paddingBlockStart: 'var(--apollo-padding-xxs)', '--provider-demo-semantic': marker },
    actions: {
      paddingInlineEnd:
        phase === 0
          ? 'var(--apollo-padding-xxs)'
          : phase === 1
            ? 'var(--apollo-padding-xs)'
            : 'var(--apollo-padding-sm)',
    },
    action: {
      color:
        phase === 0
          ? 'var(--apollo-color-text)'
          : phase === 1
            ? 'var(--apollo-color-text-secondary)'
            : 'var(--apollo-color-text)',
    },
    textarea: {
      fontSize:
        phase === 0
          ? 'var(--apollo-font-size-sm)'
          : phase === 1
            ? 'var(--apollo-font-size)'
            : 'var(--apollo-font-size-lg)',
    },
  };
  return {
    className: `demo-provider-class-${marker}`,
    style: {
      color: 'var(--apollo-color-text)',
      paddingBlockStart:
        phase === 0
          ? 'var(--apollo-padding-xs)'
          : phase === 1
            ? 'var(--apollo-padding-sm)'
            : 'var(--apollo-padding-md)',
      paddingBlockEnd: 'var(--apollo-padding-xxs)',
      '--provider-demo-style': marker,
    },
    classNames:
      phase === 2
        ? ({ props }) => ({
            ...classes,
            root: `${classes.root} ${props.prefixCls === 'apollo-typography' ? 'demo-provider-prefix-resolved' : 'demo-provider-prefix-missing'}`,
          })
        : classes,
    styles:
      phase === 2
        ? ({ props }) => ({
            ...semanticStyles,
            root: {
              ...semanticStyles.root,
              '--provider-demo-prefix': props.prefixCls ?? 'missing',
            },
          })
        : semanticStyles,
  };
};
const providerComponents = ref<NonNullable<ConfigProviderProps['components']>>({
  typography: { ...makeProviderConfig(0) },
});
const replaceProvider = () => {
  providerPhase.value = (providerPhase.value + 1) % 4;
  providerComponents.value =
    providerPhase.value === 3 ? {} : { typography: { ...makeProviderConfig(providerPhase.value) } };
};
const providerLocalStyles: TypographyProps['styles'] = {
  root: {
    color: 'var(--apollo-color-text-secondary)',
    paddingBlockEnd: 'var(--apollo-padding-xs)',
  },
  actions: { marginInlineStart: 'var(--apollo-margin-sm)' },
  action: { fontWeight: 'var(--apollo-font-weight-strong)' },
  textarea: { lineHeight: 'var(--apollo-line-height)' },
};
</script>

<template>
  <Paragraph :class-names="classNamesObject" :styles="stylesObject" :copyable="true">
    Object form: classNames / styles
  </Paragraph>
  <Paragraph :class-names="classNamesFn">Function form: classNames</Paragraph>
  <Paragraph :class-names="classNamesFn" class="demo-alt">Function form, alt</Paragraph>
  <Text :class-names="classNamesObject" :styles="stylesObject" :copyable="true" />
  <section data-native-typography-style-demo>
    <p><Button @mousedown.prevent @click="phase = (phase + 1) % 4">Cycle native typography styles</Button></p>
    <Text data-demo-native-style :class="nativeClass" :style="nativeStyle"
      :class-names="{ root: 'semantic-demo-root' }" :styles="nativeSemanticStyles">
      Native style: {{ ['string', 'array', 'object', 'removed'][phase] }}
      <Input aria-label="Semantic typography draft" style="width: min(160px, 100%); margin-top: 8px" />
    </Text>
  </section>
  <section data-typography-provider-demo>
    <p><Button @mousedown.prevent @click="replaceProvider">Replace typography provider</Button></p>
    <ConfigProvider :components="providerComponents">
      <Paragraph data-provider-demo-rich class="demo-native-provider-root" :style="{ color: 'var(--apollo-color-text)' }"
        :class-names="{ root: 'demo-local-provider-root' }" :styles="providerLocalStyles" copyable>
        Current provider: {{ ['first object', 'new object', 'function', 'removed'][providerPhase] }}
        <Input aria-label="Provider typography draft" style="width: min(160px, 100%); margin-top: 8px" />
      </Paragraph>
      <div data-provider-demo-editor>
        <Text aria-label="Provider typography editor" :editable="{ editing: true }"
          class="demo-native-provider-root" :style="{ color: 'var(--apollo-color-text)' }"
          :class-names="{ root: 'demo-local-provider-root' }" :styles="providerLocalStyles">Current provider draft</Text>
      </div>
    </ConfigProvider>
  </section>
</template>
```

## 中间省略 (ellipsis-middle)

利用 `ellipsis.suffix` 固定保留文本尾部，再用 `ellipsis.tooltip` 在悬浮时展示完整内容。

### ellipsis-middle.vue

```vue
<script setup lang="ts">
// 中间省略：固定保留尾部内容，省略中间部分
import { Text } from '@apollo-design/ui';

const text =
  'Ant Design, a design language for background applications, is refined by Ant UED Team.';
const suffixCount = 12;
const start = text.slice(0, text.length - suffixCount);
const suffix = text.slice(-suffixCount).trim();
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px; font-family: sans-serif">
    <Text :style="{ maxWidth: '260px' }" :ellipsis="{ suffix, tooltip: text }">
      {{ start }}
    </Text>
    <div style="font-size: 12px; color: var(--apollo-color-text)">
      尾部固定保留「{{ suffix }}」，悬浮可查看完整文本
    </div>
  </div>
</template>
```

## 受控省略 (ellipsis-controlled)

通过 `ellipsis.expanded` 与 `ellipsis.onExpand` 受控管理展开状态，也可用按钮从外部切换。

### ellipsis-controlled.vue

```vue
<script setup lang="ts">
// 受控展开：expanded + onExpand
import type { EllipsisConfig } from '@apollo-design/ui';
import { Button, Paragraph } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const expanded = ref(false);
const longText =
  'Ant Design, a design language for background applications, is refined by Ant UED Team. ' +
  'This sentence is intentionally long enough to overflow a narrow box, so the component has ' +
  'to decide where to cut it.';

function onExpand(_event: MouseEvent, info: { expanded: boolean }): void {
  expanded.value = info.expanded;
}

function toggle(): void {
  expanded.value = !expanded.value;
}

const symbol = (isExpanded: boolean): string => (isExpanded ? '收起' : '展开');

const ellipsisConfig = computed<EllipsisConfig>(() => ({
  rows: 2,
  expandable: true,
  expanded: expanded.value,
  onExpand,
  symbol,
}));
</script>

<template>
  <div
    style="display: flex; flex-direction: column; gap: 12px; width: min(280px, 100%); font-family: sans-serif"
  >
    <Paragraph :ellipsis="ellipsisConfig">{{ longText }}</Paragraph>
    <div>
      <Button size="small" @click="toggle">切换 expanded</Button>
      <span style="margin-left: 8px; color: var(--apollo-color-text); font-size: 12px">
        当前：{{ expanded ? '展开' : '收起' }}
      </span>
    </div>
  </div>
</template>
```

## 可展开 (ellipsis-expandable)

`ellipsis.expandable` 传 `'collapsible'` 时展开后仍可收起，配合 `symbol` 可自定义展开 / 收起文案。

### ellipsis-expandable.vue

```vue
<script setup lang="ts">
// expandable：展开后是否还能收起，以及自定义展开文案
import type { EllipsisConfig } from '@apollo-design/ui';
import { Paragraph } from '@apollo-design/ui';
import { ref } from 'vue';

const longText =
  'Ant Design, a design language for background applications, is refined by Ant UED Team. ' +
  'This sentence is intentionally long enough to overflow a narrow box, so the component has ' +
  'to decide where to cut it.';

const lastAction = ref('');

function onExpand(_event: MouseEvent, info: { expanded: boolean }): void {
  lastAction.value = info.expanded ? '展开' : '收起';
}

const symbol = (isExpanded: boolean): string => (isExpanded ? '收起' : '展开更多');

const basicConfig: EllipsisConfig = { rows: 2, expandable: true };
const collapsibleConfig: EllipsisConfig = {
  rows: 2,
  expandable: 'collapsible',
  symbol,
  onExpand,
};
</script>

<template>
  <div
    style="display: flex; flex-direction: column; gap: 16px; width: min(300px, 100%); font-family: sans-serif"
  >
    <Paragraph :ellipsis="basicConfig">{{ longText }}</Paragraph>
    <Paragraph :ellipsis="collapsibleConfig">{{ longText }}</Paragraph>
    <div style="font-size: 12px; color: var(--apollo-color-text)">最近一次操作：{{ lastAction || '-' }}</div>
  </div>
</template>
```

## 自定义编辑 (editable-custom)

`editable` 支持自定义 `icon`、`triggerType`、`maxLength` 与多行 `autoSize`，`onChange` 可实时回写保存后的文本。

### editable-custom.vue

```vue
<script setup lang="ts">
// editable 变体：自定义图标、触发方式、maxLength 与多行 autoSize
import { EditOutlined } from '@apollo-design/icons';
import type { EditConfig } from '@apollo-design/ui';
import { Paragraph, Text } from '@apollo-design/ui';
import { computed, h, ref } from 'vue';

const text = ref('点击图标或文字进入编辑');
const saved = ref(text.value);

const editableConfig = computed<EditConfig>(() => ({
  text: text.value,
  onChange: (value: string) => {
    text.value = value;
    saved.value = value;
  },
  triggerType: ['icon', 'text'],
  maxLength: 20,
  icon: h(EditOutlined),
  tooltip: '编辑这段文字',
}));

const paragraph = ref('多行可编辑段落：编辑框会随内容自动撑高，按 Enter 保存，按 Esc 取消。');
const paragraphConfig = computed<EditConfig>(() => ({
  text: paragraph.value,
  onChange: (value: string) => {
    paragraph.value = value;
  },
  autoSize: { minRows: 2, maxRows: 5 },
  enterIcon: null,
}));
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; font-family: sans-serif">
    <div>
      <Text :editable="editableConfig">{{ text }}</Text>
    </div>
    <div style="font-size: 12px; color: var(--apollo-color-text)">保存后的值：{{ saved }}</div>
    <Paragraph :editable="paragraphConfig" :style="{ width: 'min(320px, 100%)' }">
      {{ paragraph }}
    </Paragraph>
  </div>
</template>
```

## 省略后缀 (suffix)

`ellipsis.suffix` 在省略号之后追加自定义文本。一旦提供 `suffix`，组件会从 CSS 省略切换到 JS 二分裁剪，因为省略号后还需要渲染额外内容。

### suffix.vue

```vue
<script setup lang="ts">
// 省略后缀：在省略号后追加自定义文本
import { Paragraph, Text } from '@apollo-design/ui';

const longText =
  'Apollo Design UI 以 Vue 3.5 与 TypeScript 原生实现，组件行为、视觉与 DOM 结构对齐参考实现。' +
  '这段文字故意写得很长，用来观察省略号之后追加的后缀文本。';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: min(320px, 100%)">
    <Paragraph :ellipsis="{ rows: 2, suffix: '…… 查看全文' }">
      {{ longText }}
    </Paragraph>
    <Text :ellipsis="{ suffix: '… 更多' }" :style="{ display: 'block', width: '260px' }">
      {{ longText }}
    </Text>
    <p style="margin: 0; color: var(--apollo-color-text); font-size: 12px">
      suffix 会触发 JS 裁剪：省略号后还能继续放置内容。
    </p>
  </div>
</template>
```

## 表格内文本 (table)

在 `Table` 的 `render` 中返回 `Text` / `Paragraph` 等 Typography 组件：名称使用 `strong`，角色使用 `secondary`，状态按值切换 `success` / `danger`，说明列使用省略。

### table.vue

```vue
<script setup lang="ts">
// 表格内文本：在 Table 单元格中使用 Typography 系列组件
import type { TableColumnsType } from '@apollo-design/ui';
import { Paragraph, Table, Text, Title } from '@apollo-design/ui';
import { h } from 'vue';

const columns: TableColumnsType = [
  {
    title: '成员',
    dataIndex: 'name',
    key: 'name',
    width: 160,
    render: (value: unknown) => h(Text, { strong: true }, { default: () => String(value) }),
  },
  {
    title: '角色',
    dataIndex: 'role',
    key: 'role',
    width: 180,
    render: (value: unknown) => h(Text, { type: 'secondary' }, { default: () => String(value) }),
  },
  {
    title: '状态',
    dataIndex: 'status',
    key: 'status',
    width: 120,
    render: (value: unknown) =>
      h(Text, { type: value === '正常' ? 'success' : 'danger' }, { default: () => String(value) }),
  },
  {
    title: '说明',
    dataIndex: 'note',
    key: 'note',
    render: (value: unknown) =>
      h(Paragraph, { style: 'margin: 0' }, { default: () => String(value) }),
  },
];

const data: Record<string, unknown>[] = [
  {
    key: '1',
    name: '林晓',
    role: '设计负责人',
    status: '正常',
    note: '负责设计规范与组件视觉基线。',
  },
  { key: '2', name: '周澄', role: '前端工程师', status: '正常', note: '维护文档站与示例工程。' },
  {
    key: '3',
    name: '赵岚',
    role: '质量工程师',
    status: '停用',
    note: '负责可访问性与视觉回归测试。',
  },
];
</script>

<template>
  <div style="max-width: 100%; overflow-x: auto">
    <Title :level="2" style="margin-bottom: 4px">项目成员</Title>
    <Paragraph type="secondary" style="margin-bottom: 16px">
      单元格中的名称、角色、状态与说明分别使用 Text / Paragraph 渲染。
    </Paragraph>
    <Table :columns="columns" :data-source="data" :pagination="false" :scroll="{ x: 720 }" />
  </div>
</template>
```

## 组件 Token (component-token)

通过局部 ConfigProvider 切换已有 `titleMarginTop` / `titleMarginBottom` 的默认、自定义与零值。上间距作用于排版内容后的标题，首个标题不额外增加上间距。别名示例保留：标题宿主用原生 CSS 变量覆盖字号与字重，正文和次要文字继续读取当前主题。

### component-token.vue

```vue
<script setup lang="ts">
import type { ThemeConfig } from '@apollo-design/theme';
import { Button, ConfigProvider, Paragraph, Text, Title } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const phase = ref(0);
const theme = computed<ThemeConfig | undefined>(() =>
  phase.value === 0
    ? undefined
    : {
        components: {
          Typography:
            phase.value === 1
              ? { titleMarginTop: '2em', titleMarginBottom: '0.8em' }
              : { titleMarginTop: 0, titleMarginBottom: 0 },
        },
      },
);
const headingAliases = {
  '--apollo-font-size-heading-2': '30px',
  '--apollo-font-weight-strong': '700',
};
</script>
<template>
  <section class="demo-typography-token">
    <p style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px"><Button @mousedown.prevent @click="phase = (phase + 1) % 3">Cycle title spacing</Button> {{ ['Default', 'Custom', 'Zero'][phase] }}</p>
    <ConfigProvider :theme="theme">
      <Title :level="2" :style="headingAliases">组件 Token 标题</Title>
      <Paragraph>正文颜色来自 --apollo-color-text，标题颜色来自 --apollo-color-text-heading。</Paragraph>
      <Title :level="2" data-spacing-title>段落之后的标题间距</Title>
      <Paragraph><Text type="secondary">次要文本使用 --apollo-color-text-secondary。</Text></Paragraph>
    </ConfigProvider>
    <p class="demo-typography-token__hint">切换两个已有组件 Token 的默认、自定义和零值；标题原生变量另示例字号与字重。</p>
  </section>
</template>
<style>
.demo-typography-token__hint { margin: 12px 0 0; color: var(--apollo-color-text); font-size: 12px; }
</style>
```

---

# Upload

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/upload


文件选择上传和拖拽上传。

## 何时使用

- 上传是将信息（网页、文字、图片、视频等）通过网页或者上传工具发布到远程服务器上的过程。
- 当需要上传一个或一些文件时。
- 当需要展现上传的进度时。
- 当需要使用拖拽交互时。

## 代码演示

见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/upload/demo)（23 个）。

| demo | 内容 |
|---|---|
| `basic` | 点击上传：`v-model:fileList` 受控列表 + done/uploading/error 三态 |
| `dragger` | 拖拽上传：`UploadDragger` 的虚线区 + `-drag-hover` 态 |
| `picture-card` | 照片墙：`listType="picture-card"` 缩略图 + 悬浮操作层 |

裁剪图片、外部 OSS、自定义进度条等场景依赖外部服务或额外能力，暂不提供；上传生命周期、
校验、拖拽/照片墙、手动上传与自定义请求等高频场景均已覆盖。

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| action | 上传地址。为函数时按文件动态返回（可返回 Promise） | `string \| ((file: RcFile) => string \| PromiseLike<string>)` | — |
| accept | 接受的文件类型（`string` 或 `{ format, filter: 'native' \| (file) => boolean }`） | `string \| AcceptConfig` | — |
| beforeUpload | 上传前钩子。返回 `false` 阻止上传（仍触发一次 `change`）；返回 `LIST_IGNORE` 完全忽略；返回 `File`/`Blob`/字符串替换上传内容；拒绝的 Promise 也阻止该文件上传 | `(file: RcFile, fileList: RcFile[]) => void \| boolean \| string \| Blob \| Promise<…>` | — |
| capture | 媒体捕获，透传给原生 input | `string \| boolean` | — |
| classNames | 语义化类名：`{ root, trigger, list, item }`（+ 函数形态） | `UploadSemanticClassNames \| ((info) => …)` | — |
| customRequest | 覆盖默认 XHR；第二参提供 defaultRequest，返回 abort 句柄支持取消 | `(options, { defaultRequest }) => { abort: () => void } \| void` | — |
| data | 附加表单数据（函数形态按文件求值） | `object \| ((file: RcFile) => object \| Promise<object>)` | `{}` |
| defaultFileList | 非受控的默认文件列表 | `UploadFile[]` | — |
| directory | 支持上传文件夹（走 `traverse-file-tree` 递归） | `boolean` | — |
| disabled | 是否禁用 | `boolean` | — |
| fileList | **受控**文件列表（与 `v-model:fileList` 等价） | `UploadFile[]` | — |
| headers | 上传请求头（值为 `null` 的项目会被跳过） | `Record<string, string \| null>` | — |
| isImageUrl | 覆盖「是否图片」的判定 | `(file: UploadFile) => boolean` | 内置判定 |
| listType | 列表形态 | `'text' \| 'picture' \| 'picture-card' \| 'picture-circle'` | `'text'` |
| maxCount | 最大文件数。`1` 时新文件替换旧文件；超出部分不进列表且**不触发** `change` | `number` | — |
| method | 请求方法 | `string` | `'post'` |
| multiple | 是否多选 | `boolean` | `false` |
| name | 发往服务器的字段名 | `string` | `'file'` |
| onPreview | 接管预览导航 | `(file: UploadFile) => void` | — |
| onDownload | 接管默认下载服务 | `(file: UploadFile) => void` | — |
| onRemove | 确认移除；false 阻止删除 | `(file: UploadFile) => void \| boolean \| Promise<void \| boolean>` | — |
| openFileDialogOnClick | 点击触发区是否打开文件框 | `boolean` | `true` |
| pastable | 支持从剪贴板粘贴上传（`document` 级 paste 监听） | `boolean` | — |
| previewFile | 生成 picture 族缩略图的自定义实现 | `(file: File \| Blob) => PromiseLike<string>` | 200×200 居中缩略图 |
| progress | 上传列表的进度展示配置，字段见下表 | `UploadListProgressProps` | 满宽 2px，隐藏信息 |
| showUploadList | 是否展示列表，或 `{ showPreviewIcon, showRemoveIcon, showDownloadIcon }` | `boolean \| ShowUploadListInterface` | `true` |
| type | 上传形态。`'drag'` 等价于使用 `UploadDragger` | `'select' \| 'drag'` | `'select'` |
| withCredentials | 跨域请求是否携带 cookie | `boolean` | `false` |
| class / style | 原生 attrs 落外层 wrapper；局部 style 优先于语义 root 样式 | — | — |
| hasControlInside | 触发区内是否已有可聚焦控件（决定引擎根是否带 `role="button"` / `tabIndex`） | `boolean` | `true` |
| locale | 覆盖内置文案 | `{ uploading, removeFile, downloadFile, previewFile }` | 从 `LocaleProvider` 取 |

`onPreview(file)`、`onDownload(file)` 是业务服务 Props：提供后分别接管原生预览导航和
默认 window.open 下载。`onRemove(file)` 是可选确认 Prop，返回 false 或解析为 false
的 Promise 会保留文件。它们不再重复发出同名通知事件。

fileList 代表已接受的列表，update 是提议；父级拒绝不会污染其文件对象，撤去绑定后保留
最后接受的列表。已接受的活动文件被删除或替换时中止请求，迟到回调不会改写新状态。
maxCount 同时排除超额请求。action/data/request 失败只把该文件标为 error，其他批次成员
继续上传。beforeUpload 阻止的文件仍使用含 originFileObj、没有 uploading 状态的 UploadFile
作为 change 载荷。

原生 class/style 落 wrapper，其他原生 attrs/监听器落实际交互触发区，id/name 落真实文件 input。
触发区没有内部控件时支持 Enter/Space；禁用时不进入 Tab 顺序。UploadDragger 转发 Upload
全部插槽、回调、模型事件和 ref；height 设置 wrapper 高度，hasControlInside 默认 false。

### 进度配置

| 字段 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| strokeColor | 纯色、`{ from, to }` 或百分比色标渐变；渐变方向跟随 RTL | `string \| Record<string, string>` | 主题进度色 |
| strokeWidth | 轨道厚度；数字按 px，字符串使用合法 CSS 长度 | `number \| string` | `2` |
| showInfo | 显示当前百分比信息 | `boolean` | `false` |
| size | 数字为宽高，数组为 `[宽, 高]`；宽度非正时自适应，预设 small/default 的厚度为 6/8px | `number \| [number, number] \| 'small' \| 'default'` | `[-1, 2]` |
| aria-label | 实际进度条的可访问名称；覆盖文件值，未提供时使用文件名 | `string` | 文件名称 |
| aria-labelledby | 实际进度条所关联的标签 ID；覆盖文件值 | `string` | — |

数字或数组 size 决定宽高；其余情况下显式 strokeWidth 优先于预设与默认厚度。
部分 progress 对象也保留满宽 2px 的默认值。当前 Provider 的
`components.upload.progress` 与局部配置浅合并，局部字段优先，动态替换或移除立即生效。

进度值来自 `UploadFile.percent`，保留有限小数并限制在 0–100，非有限输入按 0。
文件没有 percent 字段时不显示进度，显式 undefined 或 0 表示零进度。
列表项首次挂载后等待 300ms，随后仅在 uploading 状态显示；达到 100% 仍等待上传成功事件。
整行 itemRender 插槽负责其自身内容。该配置不包含 Progress 的 percent/type/status 等其他字段。

### 事件

| 事件名 | 说明 | 参数 |
|---|---|---|
| `update:fileList` | 受控更新（`v-model:fileList`） | `fileList` |
| `change` | 每次状态推进（uploading / done / error / removed）触发一次；batchStart 时**逐文件**触发 | `{ file, fileList, event? }` |
| `drop` | 拖拽释放（只走事件通道） | `DragEvent` |

### 插槽

| 名称 | 作用域 | 说明 |
|---|---|---|
| default | — | 触发区内容。`type="drag"` 时落在 `-drag-container`；`picture-card` / `picture-circle` 时作为列表尾部上传按钮 |
| iconRender | `{ file, listType }` | 自定义列表项图标（原 `iconRender` prop，已改为 slot） |
| itemRender | `{ originNode, file, fileList, actions }` | 自定义列表项整体渲染（原 `itemRender` prop，已改为 slot） |
| removeIcon | `{ file }` | 自定义删除图标（原 `showUploadList.removeIcon`） |
| previewIcon | `{ file }` | 自定义预览图标（原 `showUploadList.previewIcon`） |
| downloadIcon | `{ file }` | 自定义下载图标（原 `showUploadList.downloadIcon`） |
| extra | `{ file }` | 自定义列表项附加内容（原 `showUploadList.extra`） |
| appendAction | — | picture-card/circle 尾部上传触发区内容，保留真实 input 与全部节点；存在的空插槽也优先 |

### Expose

| 名称 | 说明 |
|---|---|
| `nativeElement` | 根元素（`HTMLElement \| null`） |
| `fileList` | 当前文件列表 |
| `upload` | 引擎句柄：abort(fileOrUid?)、uploadFiles(files): Promise<void>、getInputRef() |
| `onBatchStart` / `onSuccess` / `onProgress` / `onError` | 程序化生命周期方法，通常由内部引擎调用 |

### 类型

`UploadFile`、`UploadProps`、`UploadChangeParam`、`UploadListType`、`ItemRender`、
`ShowUploadListInterface`、`UploadLocale`、`UploadRef`、`UploadSlots`、`UploadConfig`、`DraggerProps`、`RcFile`（= `File & { uid }`）、
`LIST_IGNORE`（`beforeUpload` 的忽略哨兵值）。

## 设计说明

- **自定义请求**：`customRequest` 是替换上传实现的入口；默认使用 XHR + FormData。
- **列表动效**：非 picture 族使用高度展开/收起动效，picture 族使用淡入淡出；
  `motionName = {p}-animate[-inline]`，并带 2000ms 兜底。
- **进度与错误提示**：列表内联轻量进度条，错误信息通过原生 `title` 提示。
- **全局基础样式不注入**：名字为裸 `<a>`、触发区里放原生 `<button>` 时，
  链接色与表单控件归一化取决于使用者自己的全局样式—— 建议配合
  任意 CSS reset 使用，或直接用组件库内的 `Button` / `Link`。

缩略图在挂载后生成，来源或处理器替换会更新，只保存在本地，不向受控文件写入 thumbUrl。
移除或卸载后忽略迟到结果，并释放内置图片预览的资源。当前 theme.components.Upload 的
令牌 actionsColor/pictureCardSize 会实时消费；原生 CSS 变量可覆盖，默认卡片尺寸跟随 controlHeightLG。

0.0.0 开发版移除没有实际消费者的 supportServerRender/styleAttrs：SSR 直接支持，根样式用
原生 style；无兼容层、无弃用期。


## 基本 (basic)

经典款式，用户点击按钮弹出文件选择框。触发控件使用库自身的 `Button`，上传由本地 mock `customRequest` 完成，不依赖外网接口。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/basic.tsx
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadFile, type UploadProps } from '@apollo-design/ui';
import { ref } from 'vue';

/** 本地缩略图（data URL），示例不依赖外网图片。 */
const thumbUrl = `data:image/svg+xml;utf8,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" width="120" height="120"><rect width="120" height="120" fill="#1677ff" opacity="0.14"/><circle cx="60" cy="60" r="26" fill="#1677ff"/></svg>',
)}`;

const fileList = ref<UploadFile[]>([
  { uid: '-1', name: 'demo.png', status: 'done', url: thumbUrl, thumbUrl },
]);

/**
 * 示例用可控 mock：不访问网络，400ms 后上传成功。
 * 真实项目把 customRequest 换成 `action` 或自己的请求函数即可。
 */
const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setInterval(() => {
    onProgress?.({ percent: 100 });
    if (timer) {
      window.clearInterval(timer);
      onSuccess?.({ ok: true });
    }
  }, 400);
  return {
    abort: () => window.clearInterval(timer),
  };
};

const handleChange: UploadProps['onChange'] = (info) => {
  fileList.value = info.fileList;
};
</script>

<template>
  <Upload
    v-model:file-list="fileList"
    action="/upload.do"
    :custom-request="customRequest"
    @change="handleChange"
  >
    <Button>
      <template #icon><UploadOutlined /></template>
      Click to Upload
    </Button>
  </Upload>
</template>
```

## 拖拽上传 (dragger)

把文件拖入后上传，支持点击选择与批量文件。示例的 `customRequest` 为本地 mock，随机数以外不依赖任何外部服务。

### dragger.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/drag.tsx
import { InboxOutlined } from '@apollo-design/icons';
import { UploadDragger, type UploadProps } from '@apollo-design/ui';

/** 本地 mock：拖入文件后 500ms 成功，不访问网络。 */
const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 500);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <UploadDragger
    action="/upload.do"
    name="file"
    multiple
    :custom-request="customRequest"
    :show-upload-list="{ showDownloadIcon: true, showPreviewIcon: true }"
  >
    <p class="demo-drag-icon"><InboxOutlined /></p>
    <p class="demo-drag-text">Click or drag file to this area to upload</p>
    <p class="demo-drag-hint">
      支持单个或批量拖入；示例使用本地 mock，不会把文件发到外网。
    </p>
  </UploadDragger>
</template>
```

## 照片墙 (picture-card)

以卡片形式展示图片缩略图，使用 `list-type="picture-card"`。缩略图来自本地 data URL，示例不依赖外网图片。

### picture-card.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/picture-card.tsx
import { PlusOutlined } from '@apollo-design/icons';
import { Upload, type UploadFile, type UploadProps } from '@apollo-design/ui';
import { ref } from 'vue';

/** 本地缩略图（data URL），不依赖外网图片。 */
const thumbUrl = `data:image/svg+xml;utf8,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" width="120" height="120"><rect width="120" height="120" fill="#fa8c16" opacity="0.16"/><path d="M30 78l22-26 16 18 12-10 20 24z" fill="#fa8c16"/><circle cx="44" cy="40" r="9" fill="#fa8c16"/></svg>',
)}`;

const fileList = ref<UploadFile[]>([
  { uid: '-1', name: 'image.png', status: 'done', url: thumbUrl, thumbUrl },
]);

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 600);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <Upload
    v-model:file-list="fileList"
    action="/upload.do"
    list-type="picture-card"
    :custom-request="customRequest"
  >
    <div>
      <PlusOutlined />
      <div style="margin-top: 8px">Upload</div>
    </div>
  </Upload>
</template>
```

## 限制数量 (max-count)

通过 `maxCount` 限制最多保留的文件数；超出时新文件会替换最早的文件（`maxCount={1}` 时行为最明显）。

### max-count.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/max-count.tsx
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadProps } from '@apollo-design/ui';

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <Upload action="/upload.do" multiple :max-count="2" :custom-request="customRequest">
    <Button>
      <template #icon><UploadOutlined /></template>
      Upload (Max: 2)
    </Button>
  </Upload>
</template>
```

## 类型与大小校验 (accept)

`accept` 限定文件选择器；`beforeUpload` 里做真实校验：非图片或超过 1MB 时用 `message.error` 提示并返回 `Upload.LIST_IGNORE`，文件不会进入列表。

### accept.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/accept.tsx + 大小校验
import { UploadOutlined } from '@apollo-design/icons';
import { Button, message, Upload, type UploadProps } from '@apollo-design/ui';

const beforeUpload: UploadProps['beforeUpload'] = (file) => {
  const isImage = file.type.startsWith('image/');
  if (!isImage) {
    message.error(`${file.name} 不是图片文件`);
    return Upload.LIST_IGNORE;
  }
  const withinLimit = file.size / 1024 / 1024 < 1;
  if (!withinLimit) {
    message.error(`${file.name} 超过 1MB`);
    return Upload.LIST_IGNORE;
  }
  return true;
};

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <Upload
    action="/upload.do"
    accept="image/*"
    :before-upload="beforeUpload"
    :custom-request="customRequest"
  >
    <Button>
      <template #icon><UploadOutlined /></template>
      Upload Image
    </Button>
  </Upload>
</template>
```

## 上传前置钩子 (before-upload)

对比 `beforeUpload` 的两种拒绝语义：返回 `false` 时文件仍进入列表但不发送请求；返回 `Upload.LIST_IGNORE` 时文件被完全忽略。两者都不会产生网络请求。

### before-upload.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/before-upload.tsx（false / LIST_IGNORE 两种语义）
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Space, Upload, type UploadProps } from '@apollo-design/ui';

/** 返回 false：进入列表但**不发起上传**（仍触发一次 change）。 */
const blockUpload: UploadProps['beforeUpload'] = () => false;

/** 返回 LIST_IGNORE：完全不进入列表，也不上传。 */
const ignoreUpload: UploadProps['beforeUpload'] = () => Upload.LIST_IGNORE;
</script>

<template>
  <Space wrap>
    <Upload action="/upload.do" :before-upload="blockUpload">
      <Button>
        <template #icon><UploadOutlined /></template>
        beforeUpload: false
      </Button>
    </Upload>
    <Upload action="/upload.do" :before-upload="ignoreUpload">
      <Button>
        <template #icon><UploadOutlined /></template>
        beforeUpload: LIST_IGNORE
      </Button>
    </Upload>
  </Space>
</template>
```

## 自定义上传 (custom-request)

用 `customRequest` 接管上传：示例每 200ms 上报一次 `onProgress`，到 100% 后调用 `onSuccess`。真实项目可在此接入自己的请求库、鉴权或分片逻辑。

### custom-request.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/custom-request.tsx（本地模拟进度，不访问网络）
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadProps } from '@apollo-design/ui';

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  let percent = 0;
  const timer = window.setInterval(() => {
    percent = Math.min(100, percent + 20);
    onProgress?.({ percent });
    if (percent >= 100) {
      window.clearInterval(timer);
      onSuccess?.({ ok: true });
    }
  }, 200);
  return { abort: () => window.clearInterval(timer) };
};
</script>

<template>
  <Upload action="/upload.do" :custom-request="customRequest">
    <Button>
      <template #icon><UploadOutlined /></template>
      Upload with Progress
    </Button>
  </Upload>
</template>
```

## 上传失败 (custom-request-error)

`customRequest` 里调用 `onError` 后，列表项进入 `error` 状态并保留文件信息，便于用户重试或移除。

### custom-request-error.vue

```vue
<script setup lang="ts">
// 对齐 antd 的上传失败态：onError 驱动列表的 error 状态
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadProps } from '@apollo-design/ui';

const customRequest: UploadProps['customRequest'] = ({ onProgress, onError }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    const error = new Error('模拟上传失败');
    (error as Error & { status?: number }).status = 500;
    onError?.(error);
  }, 600);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <Upload action="/upload.do" :custom-request="customRequest">
    <Button danger>
      <template #icon><UploadOutlined /></template>
      Upload (will fail)
    </Button>
  </Upload>
</template>
```

## 受控列表 (controlled)

用 `v-model:file-list` 受控管理文件列表：外部按钮可以直接清空列表，页面上的文件数与列表状态始终一致。

### controlled.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/controlled.tsx
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Space, Upload, type UploadFile, type UploadProps } from '@apollo-design/ui';
import { computed, ref } from 'vue';

const fileList = ref<UploadFile[]>([]);
const count = computed(() => fileList.value.length);

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 500);
  return { abort: () => window.clearTimeout(timer) };
};

const clear = () => {
  fileList.value = [];
};
</script>

<template>
  <Space orientation="vertical">
    <Upload
      v-model:file-list="fileList"
      action="/upload.do"
      :custom-request="customRequest"
    >
      <Button>
        <template #icon><UploadOutlined /></template>
        Upload
      </Button>
    </Upload>
    <Space>
      <span>文件数：{{ count }}</span>
      <Button size="small" :disabled="count === 0" @click="clear">清空列表</Button>
    </Space>
  </Space>
</template>
```

## 圆形照片墙 (picture-circle)

`list-type="picture-circle"` 把缩略图渲染成圆形，常用于头像或头像组场景。

### picture-circle.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/picture-circle.tsx
import { PlusOutlined } from '@apollo-design/icons';
import { Upload, type UploadFile, type UploadProps } from '@apollo-design/ui';
import { ref } from 'vue';

const thumbUrl = `data:image/svg+xml;utf8,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" width="120" height="120"><rect width="120" height="120" fill="#52c41a" opacity="0.16"/><path d="M28 80l20-24 14 16 10-8 20 24z" fill="#52c41a"/><circle cx="45" cy="42" r="8" fill="#52c41a"/></svg>',
)}`;

const fileList = ref<UploadFile[]>([
  { uid: '-1', name: 'circle.png', status: 'done', url: thumbUrl, thumbUrl },
]);

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 500);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <Upload
    v-model:file-list="fileList"
    action="/upload.do"
    list-type="picture-circle"
    :custom-request="customRequest"
  >
    <PlusOutlined />
  </Upload>
</template>
```

## 文件夹上传 (directory)

设置 `directory` 后文件选择器以文件夹模式打开，选中的目录会被遍历为多个文件。示例仍由本地 mock 完成上传。

### directory.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/directory.tsx
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadProps } from '@apollo-design/ui';

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <Upload action="/upload.do" directory multiple :custom-request="customRequest">
    <Button>
      <template #icon><UploadOutlined /></template>
      Upload Directory
    </Button>
  </Upload>
</template>
```

## 粘贴上传 (paste)

`pastable` 会监听页面粘贴事件，剪贴板中的图片会直接进入上传流程。浏览器需要在用户授权/聚焦的页面中触发粘贴。

### paste.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/paste.tsx
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadProps } from '@apollo-design/ui';

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <Upload action="/upload.do" pastable :custom-request="customRequest">
    <Button>
      <template #icon><UploadOutlined /></template>
      点击选择，或直接 Ctrl+V 粘贴图片
    </Button>
  </Upload>
</template>
```

## 手动上传 (manual-upload)

`customRequest` 先把请求挂起，文件保持在 uploading 状态；点击 “Start Upload” 后才逐项推进进度并成功。演示了“先选择、后提交”的受控上传流程。

### manual-upload.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/upload-manually.tsx —— 先选文件，点按钮才开始上传
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Space, Upload, type UploadProps } from '@apollo-design/ui';
import { ref } from 'vue';

type PendingRequest = Parameters<NonNullable<UploadProps['customRequest']>>[0];
const pending = ref<PendingRequest[]>([]);
const timers = new Map<PendingRequest, number>();

/** 只登记请求，不调用 onSuccess ⇒ 文件停在 uploading，等待手动触发。 */
const customRequest: UploadProps['customRequest'] = (options) => {
  pending.value.push(options);
  return {
    abort: () => {
      window.clearInterval(timers.get(options));
      timers.delete(options);
      pending.value = pending.value.filter((item) => item !== options);
    },
  };
};

const startUpload = () => {
  const queue = pending.value;
  pending.value = [];
  for (const options of queue) {
    let percent = 0;
    const timer = window.setInterval(() => {
      percent = Math.min(100, percent + 25);
      options.onProgress?.({ percent });
      if (percent >= 100) {
        window.clearInterval(timer);
        timers.delete(options);
        options.onSuccess?.({ ok: true });
      }
    }, 200);
    timers.set(options, timer);
  }
};
</script>

<template>
  <Space orientation="vertical">
    <Upload action="/upload.do" multiple :custom-request="customRequest">
      <Button>
        <template #icon><UploadOutlined /></template>
        Select Files
      </Button>
    </Upload>
    <Button type="primary" :disabled="pending.length === 0" @click="startUpload">
      Start Upload ({{ pending.length }})
    </Button>
  </Space>
</template>
```

## 列表操作 (show-list-actions)

通过 `showUploadList` 打开预览、下载与移除按钮，并用 `onPreview` / `onDownload` 接管动作。示例用 `message` 反馈，不真正打开外部链接。

### show-list-actions.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/upload-list-actions：列表上的预览/下载动作
import { UploadOutlined } from '@apollo-design/icons';
import { Button, message, Upload, type UploadFile, type UploadProps } from '@apollo-design/ui';
import { ref } from 'vue';

const thumbUrl = `data:image/svg+xml;utf8,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" width="120" height="120"><rect width="120" height="120" fill="#722ed1" opacity="0.15"/><rect x="26" y="26" width="68" height="68" rx="10" fill="#722ed1"/></svg>',
)}`;

const fileList = ref<UploadFile[]>([
  { uid: '-1', name: 'report.png', status: 'done', url: thumbUrl, thumbUrl },
]);

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};

const onPreview: UploadProps['onPreview'] = (file) => {
  message.info(`预览：${file.name}`);
};

const onDownload: UploadProps['onDownload'] = (file) => {
  message.info(`下载：${file.name}`);
};
</script>

<template>
  <Upload
    v-model:file-list="fileList"
    action="/upload.do"
    :custom-request="customRequest"
    :show-upload-list="{
      showDownloadIcon: true,
      showPreviewIcon: true,
      showRemoveIcon: true,
    }"
    :on-preview="onPreview"
    :on-download="onDownload"
  >
    <Button>
      <template #icon><UploadOutlined /></template>
      Upload
    </Button>
  </Upload>
</template>
```

## 头像上传 (avatar)

把 `Avatar` 放进 `Upload` 作为触发控件，并关闭文件列表，点击头像即可选择文件。

### avatar.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 demo/avatar.tsx：头像即上传触发器
import { UserOutlined } from '@apollo-design/icons';
import { Avatar, Upload, type UploadProps } from '@apollo-design/ui';
import { h } from 'vue';

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <Upload action="/upload.do" :show-upload-list="false" :custom-request="customRequest">
    <Avatar :size="64" :icon="h(UserOutlined)" style="cursor: pointer" />
  </Upload>
</template>
```

## 组件 Token (component-token)

通过 ConfigProvider 的 `theme.components.Upload` 设置当前组件令牌：pictureCardSize
控制图片卡片尺寸，actionsColor 控制下方文本列表的操作图标颜色。照片墙的遮罩操作维持高对比色。
示例使用本地 data URL 缩略图与 mock 上传，不访问外网；也可通过原生 style 覆盖对应 CSS 变量。

### component-token.vue

```vue
<script setup lang="ts">
// 当前 Provider 的 Upload Token 驱动实际卡片尺寸与操作图标颜色
import { PlusOutlined } from '@apollo-design/icons';
import {
  Button,
  ConfigProvider,
  Upload,
  type UploadFile,
  type UploadProps,
} from '@apollo-design/ui';
import { ref } from 'vue';

const thumbUrl = `data:image/svg+xml;utf8,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" width="120" height="120"><rect width="120" height="120" fill="#e6fffb"/><circle cx="60" cy="60" r="28" fill="#13c2c2"/></svg>',
)}`;

const fileList = ref<UploadFile[]>([
  { uid: '-1', name: 'theme-cover.png', status: 'done', url: thumbUrl, thumbUrl },
]);

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <div class="demo-upload-token">
    <ConfigProvider
      :theme="{ components: { Upload: { pictureCardSize: 96, actionsColor: '#08979c' } } }"
    >
      <Upload
        v-model:file-list="fileList"
        action="/upload.do"
        list-type="picture-card"
        :custom-request="customRequest"
      >
        <Button :icon="PlusOutlined" aria-label="上传图片">Upload</Button>
      </Upload>
      <Upload
        v-model:file-list="fileList"
        :show-upload-list="{ showDownloadIcon: true }"
        :custom-request="customRequest"
      />
    </ConfigProvider>
    <p class="demo-upload-token__hint">
      卡片尺寸来自 --apollo-upload-picture-card-size，列表操作图标颜色来自
      --apollo-upload-actions-color。
    </p>
  </div>
</template>

<style>
.demo-upload-token__hint {
  margin: 12px 0 0;
  color: #999;
  font-size: 12px;
}
</style>
```

## 默认文件列表 (default-file-list)

用 `defaultFileList` 提供非受控的初始文件列表，后续变化由组件内部维护；`onChange` 用于展示最近一次文件状态变化。上传过程由本地 mock `customRequest` 完成。

### default-file-list.vue

```vue
<script setup lang="ts">
// 默认文件列表：通过 defaultFileList 提供初始文件
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadFile, type UploadProps } from '@apollo-design/ui';
import { ref } from 'vue';

const defaultFileList: UploadFile[] = [
  { uid: '-1', name: 'annual-report-2025.pdf', status: 'done', size: 328_000 },
  { uid: '-2', name: 'brand-guidelines.md', status: 'done', size: 12_400 },
  { uid: '-3', name: 'design-assets.zip', status: 'done', size: 8_600_000 },
];

const lastChange = ref('尚未新增文件');

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};

const onChange: UploadProps['onChange'] = (info) => {
  lastChange.value = `${info.file.name}：${info.file.status ?? 'unknown'}`;
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: 420px; max-width: 100%">
    <Upload
      action="/upload.do"
      :default-file-list="defaultFileList"
      :custom-request="customRequest"
      @change="onChange"
    >
      <Button>
        <template #icon><UploadOutlined /></template>
        继续上传
      </Button>
    </Upload>
    <p aria-live="polite" style="margin: 0; color: #999; font-size: 12px">
      最近变化：{{ lastChange }}
    </p>
  </div>
</template>
```

## 文件类型图标 (file-type)

`#iconRender` 作用域插槽收到 `{ file, listType }`，可按扩展名为文件列表渲染不同图标。示例使用 `listType="picture"` 且不提供缩略图，因此列表会展示自定义图标。

### file-type.vue

```vue
<script setup lang="ts">
// 文件类型：通过 #iconRender 为不同扩展名渲染不同图标
import {
  FileExcelOutlined,
  FileImageOutlined,
  FileMarkdownOutlined,
  FilePdfOutlined,
  FileTextOutlined,
  FileWordOutlined,
  FileZipOutlined,
  UploadOutlined,
} from '@apollo-design/icons';
import { Button, Upload, type UploadFile, type UploadProps } from '@apollo-design/ui';
import { type Component, ref } from 'vue';

const iconMap: Record<string, Component> = {
  pdf: FilePdfOutlined,
  md: FileMarkdownOutlined,
  zip: FileZipOutlined,
  xlsx: FileExcelOutlined,
  docx: FileWordOutlined,
  png: FileImageOutlined,
  jpg: FileImageOutlined,
};

const iconFor = (name: string): Component => {
  const ext = name.split('.').pop()?.toLowerCase() ?? '';
  return iconMap[ext] ?? FileTextOutlined;
};

const fileList = ref<UploadFile[]>([
  { uid: '-1', name: 'quarterly-report.pdf', status: 'done' },
  { uid: '-2', name: 'release-notes.md', status: 'done' },
  { uid: '-3', name: 'assets.zip', status: 'done' },
]);

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <div style="width: 420px; max-width: 100%">
    <Upload
      v-model:file-list="fileList"
      action="/upload.do"
      list-type="picture"
      :custom-request="customRequest"
    >
      <Button>
        <template #icon><UploadOutlined /></template>
        上传任意文件
      </Button>
      <template #iconRender="{ file }">
        <component :is="iconFor(file.name)" aria-hidden="true" />
      </template>
    </Upload>
    <p style="margin: 12px 0 0; color: #999; font-size: 12px">
      列表图标由 #iconRender 根据文件扩展名选择；示例文件没有缩略图。
    </p>
  </div>
</template>
```

## 文件预览 (preview-file)

通过 `onPreview` 接管文件预览：示例在页面内展示本地 data URL 图片，并提供可访问的「关闭预览」按钮。文件列表的预览图标带有本地化 `aria-label`，可用键盘操作。

### preview-file.vue

```vue
<script setup lang="ts">
// 文件预览：点击列表预览图标后在页面内展示本地图片
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadFile, type UploadProps } from '@apollo-design/ui';
import { ref } from 'vue';

const thumbUrl = `data:image/svg+xml;utf8,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="160"><rect width="240" height="160" fill="#f9f0ff"/><circle cx="70" cy="70" r="34" fill="#722ed1" opacity="0.8"/><rect x="120" y="50" width="80" height="60" rx="10" fill="#9254de" opacity="0.7"/></svg>',
)}`;

const defaultFileList: UploadFile[] = [
  { uid: '-1', name: 'dashboard-preview.svg', status: 'done', url: thumbUrl, thumbUrl },
];

const preview = ref<{ url: string; name: string } | null>(null);

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};

const onPreview: UploadProps['onPreview'] = (file) => {
  preview.value = { url: file.thumbUrl || file.url || '', name: file.name };
};

const closePreview = (): void => {
  preview.value = null;
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: 420px; max-width: 100%">
    <Upload
      action="/upload.do"
      list-type="picture"
      :default-file-list="defaultFileList"
      :custom-request="customRequest"
      :on-preview="onPreview"
    >
      <Button>
        <template #icon><UploadOutlined /></template>
        上传图片
      </Button>
    </Upload>

    <div v-if="preview" class="demo-upload-preview" aria-live="polite">
      <img :src="preview.url" :alt="`预览：${preview.name}`" class="demo-upload-preview__image" />
      <div class="demo-upload-preview__meta">
        <span>{{ preview.name }}</span>
        <Button html-type="button" size="small" @click="closePreview">关闭预览</Button>
      </div>
    </div>
    <p v-else style="margin: 0; color: #999; font-size: 12px">
      点击文件列表中的预览图标查看本地图片。
    </p>
  </div>
</template>

<style>
.demo-upload-preview {
  padding: 12px;
  border: 1px solid #d3adf7;
  border-radius: 8px;
  background: #f9f0ff;
}

.demo-upload-preview__image {
  display: block;
  max-width: 100%;
  border-radius: 4px;
}

.demo-upload-preview__meta {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  margin-top: 8px;
  font-size: 12px;
}
</style>
```

## 语义化样式与类 (style-class)

Upload 提供 `root` / `list` / `item` / `trigger` 四个语义槽。示例为列表和条目设置类名与内联样式，展示「类名拼接、样式覆盖」的用法；上传由本地 mock 完成。

### style-class.vue

```vue
<script setup lang="ts">
// 语义化样式与类：root / list / item 三个槽位
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadFile, type UploadProps } from '@apollo-design/ui';
import { ref } from 'vue';

const fileList = ref<UploadFile[]>([
  { uid: '-1', name: 'semantic-list.md', status: 'done' },
  { uid: '-2', name: 'semantic-preview.pdf', status: 'done' },
]);

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <div style="width: 420px; max-width: 100%">
    <Upload
      v-model:file-list="fileList"
      action="/upload.do"
      :custom-request="customRequest"
      :class-names="{
        root: 'demo-upload-style',
        list: 'demo-upload-style__list',
        item: 'demo-upload-style__item',
      }"
      :styles="{
        list: { backgroundColor: '#f9f0ff', padding: '8px', borderRadius: '8px' },
        item: { paddingInline: '8px' },
      }"
    >
      <Button>
        <template #icon><UploadOutlined /></template>
        上传文件
      </Button>
    </Upload>
    <p style="margin: 12px 0 0; color: #999; font-size: 12px">
      classNames 负责拼接类名，styles 负责覆盖列表与条目的内联样式。
    </p>
  </div>
</template>

<style>
.demo-upload-style__list {
  border: 1px dashed #d3adf7;
}

.demo-upload-style__item {
  color: #531dab;
}
</style>
```

## 上传前转换文件 (transform-file)

本仓不提供已废弃的 `transformFile` 属性；等价能力由 `beforeUpload` 返回新的 `File` 完成。示例把文件名中的空格替换为连字符并转成小写，再交给 mock 上传。

### transform-file.vue

```vue
<script setup lang="ts">
// 上传前转换文件：beforeUpload 返回新的 File 替换原始文件
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadProps } from '@apollo-design/ui';
import { ref } from 'vue';

const transformed = ref('尚未选择文件');

const beforeUpload: UploadProps['beforeUpload'] = (file) => {
  const safeName = file.name.replace(/\s+/g, '-').toLowerCase();
  const nextFile = new File([file], safeName, {
    type: file.type,
    lastModified: file.lastModified,
  });
  transformed.value = `${file.name} → ${nextFile.name}`;
  return nextFile;
};

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: 420px; max-width: 100%">
    <Upload action="/upload.do" :before-upload="beforeUpload" :custom-request="customRequest">
      <Button>
        <template #icon><UploadOutlined /></template>
        选择文件并转换名称
      </Button>
    </Upload>
    <p aria-live="polite" style="margin: 0; color: #999; font-size: 12px">
      转换结果：{{ transformed }}
    </p>
  </div>
</template>
```

## 仅限 PNG (upload-png-only)

`accept="image/png"` 只影响文件选择框的过滤，真正的类型校验放在 `beforeUpload`：非 PNG 文件会提示错误并返回 `Upload.LIST_IGNORE`，不会进入列表。

### upload-png-only.vue

```vue
<script setup lang="ts">
// 仅允许 PNG：beforeUpload 校验类型并拒绝其他文件
import { UploadOutlined } from '@apollo-design/icons';
import { Button, message, Upload, type UploadProps } from '@apollo-design/ui';
import { ref } from 'vue';

const lastResult = ref('尚未选择文件');

const beforeUpload: UploadProps['beforeUpload'] = (file) => {
  if (file.type !== 'image/png') {
    message.error(`${file.name} 不是 PNG 文件`);
    lastResult.value = `${file.name}：已拒绝（仅支持 PNG）`;
    return Upload.LIST_IGNORE;
  }
  lastResult.value = `${file.name}：类型校验通过`;
  return true;
};

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  const timer = window.setTimeout(() => {
    onProgress?.({ percent: 100 });
    onSuccess?.({ ok: true });
  }, 400);
  return { abort: () => window.clearTimeout(timer) };
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: 420px; max-width: 100%">
    <Upload
      action="/upload.do"
      accept="image/png"
      :before-upload="beforeUpload"
      :custom-request="customRequest"
    >
      <Button>
        <template #icon><UploadOutlined /></template>
        选择 PNG 图片
      </Button>
    </Upload>
    <p aria-live="polite" style="margin: 0; color: #999; font-size: 12px">
      {{ lastResult }}
    </p>
  </div>
</template>
```

## 自定义进度条 (customize-progress-bar)

`progress` 支持渐变 `strokeColor`、数字或 CSS 长度 `strokeWidth`、`showInfo` 与 ARIA 名称。
本例显示 4px 渐变进度和当前百分比。初始文件从 30% 推进到 100%，新选择的文件通过
mock `customRequest` 反馈进度；成功事件后收起进度条。

### customize-progress-bar.vue

```vue
<script setup lang="ts">
// 自定义进度条：渐变、线宽、百分比信息与可访问名称
import { UploadOutlined } from '@apollo-design/icons';
import { Button, Upload, type UploadFile, type UploadProps } from '@apollo-design/ui';
import { onMounted, onUnmounted, ref } from 'vue';

const fileList = ref<UploadFile[]>([
  { uid: '-1', name: 'uploading-report.pdf', status: 'uploading', percent: 30 },
]);

let demoTimer: number | undefined;

const customRequest: UploadProps['customRequest'] = ({ onProgress, onSuccess }) => {
  let percent = 0;
  const uploadTimer = window.setInterval(() => {
    percent = Math.min(100, percent + 20);
    onProgress?.({ percent });
    if (percent >= 100) {
      window.clearInterval(uploadTimer);
      onSuccess?.({ ok: true });
    }
  }, 300);
  return { abort: () => window.clearInterval(uploadTimer) };
};

onMounted(() => {
  demoTimer = window.setInterval(() => {
    const first = fileList.value[0];
    if (first?.status !== 'uploading') {
      if (demoTimer !== undefined) window.clearInterval(demoTimer);
      demoTimer = undefined;
      return;
    }
    const nextPercent = Math.min(100, (first.percent ?? 0) + 10);
    const nextStatus: UploadFile['status'] = nextPercent >= 100 ? 'done' : 'uploading';
    fileList.value = fileList.value.map((file) =>
      file.uid === first.uid ? { ...file, percent: nextPercent, status: nextStatus } : file,
    );
    if (nextPercent >= 100 && demoTimer !== undefined) {
      window.clearInterval(demoTimer);
      demoTimer = undefined;
    }
  }, 500);
});

onUnmounted(() => {
  if (demoTimer !== undefined) window.clearInterval(demoTimer);
});
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: 420px; max-width: 100%">
    <Upload
      v-model:file-list="fileList"
      action="/upload.do"
      :custom-request="customRequest"
      :progress="{
        strokeWidth: 4,
        showInfo: true,
        strokeColor: { '0%': '#108ee9', '100%': '#87d068' },
        'aria-label': '文件上传进度',
      }"
    >
      <Button>
        <template #icon><UploadOutlined /></template>
        上传新文件
      </Button>
    </Upload>
    <p style="margin: 0; color: #999; font-size: 12px">
      渐变进度条显示当前百分比，线宽为 4px；初始文件会自动从 30% 演示到 100%。
    </p>
  </div>
</template>
```

---

# Watermark

UI version: 0.1.9
Source commit: b6578306f58bf0918d0f4cb8519cf4cf1a900b15
Page: https://apollocmh.github.io/apollo-design-ui/components/watermark


给页面区域添加不干扰内容与交互的装饰水印。参见 [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/watermark/demo) 中的文本、多行、图片、动态配置及 Modal 继承示例。

## API

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| content | 水印文本；数组按行绘制，每行可覆盖字体 | `WatermarkContent \| WatermarkContent[]` | — |
| font | 字体，见下表 | `WatermarkFont` | `colorFill`、`fontSizeLG` 及正常无衬线字体 |
| image | 图片地址，优先于文本；加载失败时绘制 `content` | `string` | — |
| width / height | 单个水印单元宽高 | `number` | 文本测量 / 图片 120×64 |
| rotate | 旋转角度（度） | `number` | `-22` |
| gap | 间距 `[x, y]` | `[number, number]` | `[100, 100]` |
| offset | 偏移 `[left, top]`；绘制锚点为 `offset - gap / 2` | `[number, number]` | `gap / 2` |
| zIndex | 装饰层层级，支持 `0` | `number` | `zIndexPopupBase - 1` |
| inherit | 注册的子孙浮层继承本层水印；关闭后转交上层，无上层时不覆盖浮层 | `boolean` | `true` |

`class`、`style`、`id`、`aria-*` 和原生事件落到根 `div`。样式优先级为默认 `position: relative; overflow: hidden` → Provider 样式 → 原生 `style`；支持 Vue 对象、数组、字符串样式。防篡改恢复也遵守当前合法覆盖。

### 字体

| 字段 | 类型 | 默认值 |
|---|---|---|
| color | `string \| CanvasGradient \| CanvasPattern` | `colorFill` |
| fontSize | `number \| string` | `fontSizeLG` |
| fontWeight | `'normal' \| 'lighter' \| 'bold' \| 'bolder' \| number` | `'normal'` |
| fontStyle | `'normal' \| 'italic' \| 'oblique'` | `'normal'` |
| fontFamily | `string` | `'sans-serif'` |
| textAlign | `CanvasTextAlign` | `'center'` |

`fontSize` 的数字与纯数字字符串按像素解释；`16px`、`2rem`、`12pt`、`calc(...)` 等合法字号交给浏览器 canvas 原生解析，再用规范后的像素测量和缩放。相对单位在重绘时求值，不单独观察外部字体加载或页面字号变化。浏览器拒绝的字体在绘制时抛出 `TypeError`，不悄悄沿用旧字体。每行字体字段为 `undefined` 时继承当前有效字体。

### 插槽与事件

| 插槽 | 说明 |
|---|---|
| default | 被水印覆盖的原生内容，无作用域参数；普通配置更新保留子树身份 |

| 事件 | 说明 | 参数 |
|---|---|---|
| remove | 受管理的水印节点被移除或换父并恢复时通知，每次恢复一次；首次绘制、主动切换继承及正常卸载不触发 | 无 |

使用 `<Watermark @remove="notify">`；程序调用的 `onRemove` 是 Vue 事件监听器，支持监听器替换和 `.once`，不再是组件回调 prop。

### Ref

`WatermarkRef.nativeElement: HTMLDivElement | null` 指向当前根元素。SSR 仅渲染根与默认槽，挂载后才开始 canvas、图片和观察器工作；卸载会取消帧、断开图片回调与观察器，并清除所管理的浮层水印。

### Theme

本组件没有样式表或 Component Token。绘制直接读取当前 `zIndexPopupBase`、`colorFill`、`fontSizeLG` alias token，支持 Provider 替换与撤除。

### 迁移

防篡改通知改为 Vue `remove` 事件。`fontStyle: 'none'` 不是有效字体值，请改为 `'normal'`。图片地址变更现在会使同尺寸缓存失效，不需要附带修改宽高。


## 基本 (basic)

最简单的用法。

### basic.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 basic demo
import { Watermark } from '@apollo-design/ui';
</script>

<template>
  <Watermark content="Ant Design">
    <div style="height: 500px" />
  </Watermark>
</template>
```

## 多行水印 (multi-line)

通过数组设置多行水印，每一行都可以有独立的字体配置。

### multi-line.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 multi-line demo
import { Watermark } from '@apollo-design/ui';
</script>

<template>
  <Watermark :content="['Ant Design', { text: 'Happy Working', font: { fontSize: 12 } }]">
    <div style="height: 500px" />
  </Watermark>
</template>
```

## 图片水印 (image)

通过 `image` 指定图片地址。为保证图片高清，请设置 `width` 和 `height`（默认 120 × 64）。

### image.vue

```vue
<script setup lang="ts">
// 对齐 antd 的 image demo
import { Watermark } from '@apollo-design/ui';
</script>

<template>
  <Watermark
    :height="30"
    :width="130"
    image="https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*lkAoRbywo0oAAAAAAAAAAAAADrJ8AQ/original"
  >
    <div style="height: 500px" />
  </Watermark>
</template>
```

## 自定义配置 (custom)

使用本库的输入框、颜色选择器、滑块和数字输入框调整水印。预览与设置面板会随容器宽度换行；偏移留空时采用默认值。

### custom.vue

```vue
<script setup lang="ts">
import {
  ColorPicker,
  type ColorPickerColor,
  Flex,
  Input,
  InputNumber,
  Slider,
  Typography,
  Watermark,
} from '@apollo-design/ui';
import { computed, ref } from 'vue';

const content = ref('Apollo Design');
const color = ref('rgba(0, 0, 0, 0.15)');
const fontSize = ref(16);
const zIndex = ref(11);
const rotate = ref(-22);
const gapX = ref<number | null>(100);
const gapY = ref<number | null>(100);
const offsetLeft = ref<number | null>(null);
const offsetTop = ref<number | null>(null);
const offset = computed<[number, number] | undefined>(() =>
  offsetLeft.value === null || offsetTop.value === null
    ? undefined
    : [offsetLeft.value, offsetTop.value],
);
function changeColor(value: ColorPickerColor) {
  color.value = value.toRgbString();
}
</script>

<template>
  <Flex gap="middle" wrap>
    <Watermark class="watermark-custom-preview" :content="content" :z-index="zIndex" :rotate="rotate" :gap="[gapX ?? 100, gapY ?? 100]" :offset="offset" :font="{ color, fontSize }">
      <Typography>
        <p>The light-speed iteration of the digital world makes products more complex. However, human consciousness and attention resources are limited.</p>
      </Typography>
      <img draggable="false" style="z-index: 10; width: 100%; max-width: 800px; position: relative" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*zx7LTI_ECSAAAAAAAAAAAABkARQnAQ" alt="Watermark preview artwork" />
    </Watermark>
    <div class="watermark-custom-controls">
      <label>Content <Input v-model:value="content" aria-label="Watermark content" placeholder="Please enter" /></label>
      <div class="watermark-custom-field"><span>Color</span><ColorPicker :value="color" aria-label="Watermark color" show-text @change="changeColor" /></div>
      <div class="watermark-custom-field"><span>Font size: {{ fontSize }}</span><Slider v-model:value="fontSize" :min="1" :max="100" aria-label-for-handle="Watermark font size" /></div>
      <div class="watermark-custom-field"><span>zIndex: {{ zIndex }}</span><Slider v-model:value="zIndex" :min="0" :max="100" aria-label-for-handle="Watermark zIndex" /></div>
      <div class="watermark-custom-field"><span>Rotate: {{ rotate }}°</span><Slider v-model:value="rotate" :min="-180" :max="180" aria-label-for-handle="Watermark rotation" /></div>
      <label>Horizontal gap <InputNumber v-model:value="gapX" :min="0" aria-label="Watermark horizontal gap" /></label>
      <label>Vertical gap <InputNumber v-model:value="gapY" :min="0" aria-label="Watermark vertical gap" /></label>
      <label>Horizontal offset <InputNumber v-model:value="offsetLeft" aria-label="Watermark horizontal offset" placeholder="Default" /></label>
      <label>Vertical offset <InputNumber v-model:value="offsetTop" aria-label="Watermark vertical offset" placeholder="Default" /></label>
    </div>
  </Flex>
</template>

<style scoped>
.watermark-custom-preview { flex: 1 1 280px; min-width: 0; }
.watermark-custom-controls { display: flex; flex: 1 1 240px; flex-direction: column; gap: 12px; min-width: 0; border: 1px solid var(--apollo-color-border); border-radius: var(--apollo-border-radius); padding: 16px; }
.watermark-custom-controls label, .watermark-custom-field { display: flex; flex-direction: column; gap: 4px; }
.watermark-custom-controls :deep(.apollo-input-number) { width: 100%; }
</style>
```

## 继承到浮层 (portal)

`Watermark` 的 `inherit` 默认开启，通过 context 把水印带到 Teleport 到 `body` 的 `Modal` 面板。

### portal.vue

```vue
<script setup lang="ts">
// 水印通过注册服务继承到实际 Teleport Modal 面板。
import { Button, Modal, Watermark } from '@apollo-design/ui';
import { ref } from 'vue';

const open = ref(false);
</script>

<template>
  <Watermark content="Apollo Design">
    <div
      style="
        padding: 24px;
        border: 1px dashed var(--apollo-color-border);
        border-radius: var(--apollo-border-radius-lg);
      "
    >
      <p style="margin-top: 0">
        页面区域带有水印；打开弹窗后，水印会继续覆盖 Teleport 出去的面板。
      </p>
      <Button type="primary" @click="open = true">Open Modal</Button>
    </div>
    <Modal
      :open="open"
      title="Watermark in Modal"
      @ok="open = false"
      @cancel="open = false"
    >
      <p>这个弹窗挂载在 body 上，仍然继承外层 Watermark。</p>
      <p>修改外层水印配置时，面板会同步更新。</p>
    </Modal>
  </Watermark>
</template>
```