# 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`.

# Getting Started

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

Apollo Design is an **independent Vue 3 + TypeScript component library** with consistent interactions, static CSS and CSS-variable themes. Its public APIs and user scenarios define the component contracts.

### Requirements

- Vue **3.5+** (Composition API)
- TypeScript 5.x (recommended)
- Modern browsers (ES2022)

### Install

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

Install `@apollo-design/icons` if you need icons. See [AI integration](https://apollocmh.github.io/apollo-design-ui/guide/ai) for versioned API documentation and examples.

### Usage

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

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

<template>
  <Space>
    <Button type="primary">Primary</Button>
    <Button>Default</Button>
  </Space>
</template>
```



---

# AI Integration

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

Apollo Design is an independent Vue 3 native UI library. Give your coding assistant its documentation before asking it to write code; do not assume React or another library's APIs.

### Documentation for AI

- [Documentation index](https://apollocmh.github.io/apollo-design-ui/llms.en.txt)
- [Full English documentation and examples](https://apollocmh.github.io/apollo-design-ui/llms-full.en.txt)
- [Full Chinese documentation and examples](https://apollocmh.github.io/apollo-design-ui/llms-full.txt)
- [Button Markdown](https://apollocmh.github.io/apollo-design-ui/components/button.en.md)

Components are available at `components/<name>.md` and `components/<name>.en.md`; guides at `guide/<slug>.md` and `guide/<slug>.en.md`. Prefer individual pages to keep context small. Files identify their UI version and source commit and update with the documentation site. Check the version before using them in an older project.

Add the index URL to your project's AI instructions and ask the assistant to read the relevant APIs and examples first. Clients do not necessarily discover `llms.txt` automatically. Use Apollo's documented Props, Slots, Emits, v-model and imports. Import `@apollo-design/theme/tokens.css` before `@apollo-design/ui/style.css`. Query missing information instead of inventing APIs.

### Local MCP

`@apollo-design/mcp` serves bundled documentation through stdio, with no network requests, account, API key or hosted server required at runtime. Use the npm package matching your UI version (currently `0.1.9`). The first npx launch downloads the package; subsequent queries read bundled files.

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

Configure your MCP client, replacing the absolute project path:

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

Node.js 22.12+ is required. `--project` resolves the application's installed `@apollo-design/ui` and checks its exact version. Missing packages and version mismatches fail explicitly. Without this option you can browse the bundle, but the project version is reported as unverified.

Read-only tools: `search_components`, `get_document`, `list_examples`, and `get_example`. They retrieve documentation and actual Vue demos with local helper files, without executing code or modifying your project. The site and MCP share the same content pipeline and public import rewriting.



---

# Styles

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

JavaScript, static component CSS and theme selection are independent. All three import strategies use the same public `ThemeConfig` and independent preset imports; resolver registration is not needed to choose or customize a theme.

The structural resources and official resolver below require UI 0.1.8 or newer.

- **Automatic:** configure `Components({ resolvers: [ApolloResolver()] })` from `unplugin-vue-components/vite` and `@apollo-design/ui-resolver`. In App.vue import `monoPreset` from `@apollo-design/theme/presets/mono` and its optional `mono.css`, then use `<AConfigProvider :theme="{ preset: monoPreset, mode: 'system' }"><AButton>Mono</AButton></AConfigProvider>`. The resolver imports public component JavaScript and the ordered structural CSS resources in `ui/style-manifest.json`; it never imports a preset or aggregate CSS. Include generated component declarations in TypeScript.
- **Manual subpaths:** import `ConfigProvider` from `@apollo-design/ui/config-provider` and `Button` from `@apollo-design/ui/button`, plus the same preset, `ui/base.css` and `ui/button/structure.css`. Complex components need their complete public manifest styles list, or their existing self-contained `ui/<component>/style.css` entry. Slot-provided components need their own styles.
- **Aggregate:** import `{ ConfigProvider, Button }` from `@apollo-design/ui`, then `ui/style.css` and the chosen preset stylesheet. The theme object and template are identical to the manual example.

For neutral structural entries, load public variables, base/component structure, then user overrides. Load legacy aggregate/self-contained styles before an optional preset so their default rules cannot replace the selection. Do not combine overlapping legacy and structural entries. Existing aggregate-style applications can set `ApolloResolver({ importStyle: false })` while retaining JavaScript resolution.

Each optional `theme/presets/default.css`, `/mono.css` or `/material3.css` contains only that preset's public derived variables for light/dark/system. Set `data-apollo-preset` and `data-apollo-theme` on the desired static scope. A single-preset application loads only that preset; Docs deliberately loads all three for its Header preview. The legacy `theme/tokens.css` still supplies default light/dark/compact scopes and is unnecessary alongside a chosen independent preset.

AutoComplete uses Select structure, TimePicker/TimeRangePicker use DatePicker, and Layout.Sider has a separate layout-sider entry. ConfigProvider needs no stylesheet of its own. Published CSS uses the default `apollo` prefix; custom prefixes require matching styles. See [Theming](https://apollocmh.github.io/apollo-design-ui/guide/theming) for user overrides, nesting and system/SSR behavior.

### Default link styles

The shared base applies themed link colors, decoration and a visible keyboard focus indicator, independently of Select. Native inline styles or application CSS can override these defaults.

### Native form controls

Shared styles preserve the browser's foreground, background and disabled colors for native controls. Apollo components declare their own theme colors. When styling a native control, set its foreground and background together. For example, `style="color: inherit; background: transparent"` lets a native button follow its parent without placing light text on the browser's light background in a dark scope.



---

# Tree Shaking

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

Apollo Design supports automatic imports through `@apollo-design/ui-resolver` and explicit imports. Its ESM modules allow bundlers to tree-shake unused exports. Component CSS and theme variables are loaded as described below.

### Automatic imports

Use `@apollo-design/ui-resolver` with `unplugin-vue-components` to import components and their structural CSS from Vue templates.

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

The current resolver supports UI `>=0.1.8 <0.2.0` and `unplugin-vue-components ^32.1.0`. Keep Apollo packages on the same release version. Your Vue project must already have `vite` and `@vitejs/plugin-vue` installed.

```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',
    }),
  ],
});
```

Include the generated `src/components.d.ts` in your application's TypeScript project. An existing `include: ["src/**/*.ts", "src/**/*.vue"]` covers it.

Load default theme variables in your application entry:

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

Use `A`-prefixed names in templates without manually importing components:

```vue
<template>
  <ASpace>
    <AButton type="primary">Save</AButton>
    <AInputSearch placeholder="Search" />
  </ASpace>
</template>
```

Compound components use explicit names such as `AInputSearch`, `AFormItem`, `ASpaceCompact` and `ALayoutSider`. Their kebab-case equivalents, such as `<a-button>`, also work in templates.

`ApolloResolver()` imports component JavaScript and the required structural CSS by default. Bundlers deduplicate repeated stylesheet paths. Your application chooses and loads the theme variables; do not also load `ui/style.css` or overlapping component `style.css` files. See [Styles](https://apollocmh.github.io/apollo-design-ui/guide/styles) and [Theming](https://apollocmh.github.io/apollo-design-ui/guide/theming) for independent presets such as Mono and Material.

If you already load aggregate CSS or want to manage styles yourself, disable automatic style imports:

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

JavaScript resolution remains enabled, while your application takes responsibility for styles. The resolver handles Vue templates. Services such as `message` and `notification`, and components used in TSX or render functions, still require explicit imports and their corresponding styles.

### Manual imports

Choose components and their self-contained stylesheets explicitly:

```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';
```

Public subpaths also work, for example `import { Button } from '@apollo-design/ui/button'`. Bundlers retain the used components and their actual JavaScript dependencies. Each component's `style.css` includes implementation-owned style dependencies. Components supplied by your application through slots need their own styles.

### Aggregate CSS

Load all component styles in your application entry:

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

Named JavaScript imports remain tree-shakeable. When combining aggregate CSS with the resolver, set `importStyle: false` to avoid overlapping styles. See [Styles](https://apollocmh.github.io/apollo-design-ui/guide/styles) for structural entries, independent presets and import order.



---

# Theming

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

[Open the theme gallery](https://apollocmh.github.io/apollo-design-ui/guide/themes) to compare all three themes in light and dark.

### Independent style and appearance

Default, Mono and Material presets use the same public `ThemePreset` and `ThemeConfig` API. Material references MUI’s neutral surfaces, 4px default corners and elevation shadows while retaining Apollo’s component interactions. Compare light and dark appearances in the [theme gallery](https://apollocmh.github.io/apollo-design-ui/guide/themes). Import `defaultPreset`, `monoPreset` or `material3Preset` from the independent `@apollo-design/theme/presets/default`, `/mono` or `/material3` entry. Each also has a default export. The root entry does not load every preset. Custom presets do not require resolver registration.

```ts
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 } },
};
```

Pass this configuration to `ConfigProvider`. `mode` accepts `light | dark | system`. Live providers subscribe to system appearance after mounting and release their subscription. Pure `getDesignToken(config, systemAppearance?)` and SSR default to light; pass `'dark'` as the second argument when the server knows the preference.

### Precedence and scope

Derivation applies default seeds, common preset tokens, the selected appearance scheme, user seeds and derivation, then final user Map/Alias overrides. Component tokens override their component defaults. A local explicit algorithm replaces an inherited mode; a local mode replaces an inherited algorithm.

`ConfigProvider` inherits raw parent configuration by default; `inherit: false` resets it. Standalone `ThemeProvider` retains its existing reset-by-default behavior; use `inherit: true` to merge the parent. Parallel/nested providers and their portals and contextual App Message/Notification APIs retain their scopes.

### Resources and preview

See [Styles](https://apollocmh.github.io/apollo-design-ui/guide/styles) for automatic, manual subpath and aggregate imports. Optional `@apollo-design/theme/presets/default.css`, `/mono.css` and `/material3.css` are generated through the same public derivation API. Load only the preset you use, then set `data-apollo-preset="mono"` and `data-apollo-theme="light|dark|system"`. Direct CSS variable overrides do not recalculate derived palettes; use a provider for seed derivation.

The Docs Header offers independent style and appearance controls on desktop and narrow screens. Preferences persist across navigation and refresh. A pre-paint script sets the public selectors before styles load; SSR keeps deterministic markup and live context starts after hydration. The site's `--site-*` aliases read the public tokens rather than duplicating palettes.

Inline demos inherit the selection while intentional local overrides remain active. Standalone URLs carry initial `preset`, `theme` and `lang`. Frames are created once with current preferences; subsequent same-origin messages verify source and frameId and update context without navigation, preserving input, selection and open state. Docs explicitly loads three optional preset stylesheets for switching; a single-preset application does not need all three.



---

# Theme gallery

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

### Compare the previews

The gallery above presents the same content in Default, Mono and Material. The first row uses light mode and the second uses dark mode. Each card owns its theme scope, so changing the surrounding site's appearance preserves the mode shown on its label. Narrow screens wrap the cards in the same order without requiring page-wide horizontal scrolling.

Edit a name, toggle notifications, or use Continue and Reset to change the progress value. State belongs to each preview independently. You can also use Tab to compare keyboard focus and disabled controls across the six appearances.

Reset restores only progress to 64. The edited name and notification switch keep their own state so you can continue comparing themes.

### Choose and customize

Default is the standard appearance, Mono uses a monochrome style, and Material references [MUI Material UI](https://github.com/mui/material-ui) for neutral surfaces, restrained corners and elevation shadows. The brand stays **#0073E6** in both appearances: filled actions darken on hover, while dark-mode text and links use lighter colors. The public `material3Preset` / `material3` names are retained, so existing imports and configuration need no renaming. See [Theming](https://apollocmh.github.io/apollo-design-ui/guide/theming) for application setup, brand overrides, appearance switching and nested scopes. This page focuses on comparing working components.



---

# Internationalization

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

Built-in component texts are provided by `@apollo-design/locale`: wrap your app with `ConfigProvider` from `@apollo-design/ui` and a locale object (`zh_CN` / `en_US` / dozens more, with stable language and region identifiers). For example, `useLocale('Table')` returns reactive computed refs for the component texts and language code. This site switches its own UI strings and component docs between zh-CN and en-US; missing translations fall back explicitly with a visible hint.



---

# Compatibility

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 形态兼容层。



---

# Icons

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

Icons live in the standalone `@apollo-design/icons` package, installed and imported separately from `@apollo-design/ui`. It ships **848 icons**: 447 Outlined, 251 Filled, and 150 TwoTone. Browse the full catalog on the [icon resource page](https://apollocmh.github.io/apollo-design-ui/components/icon).

### Install and import

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

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

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

Icons are regular Vue components. They inherit `currentColor` and `font-size`, and accept `style` / `class` overrides:

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

### TwoTone colors

Use `twoToneColor` per icon or `setTwoToneColor` globally:

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

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

### IconProvider

`IconProvider` overrides the icon class prefix (default `apollo-icon`):

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

### Custom icons

```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',
);
```

For iconfont.cn:

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

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

### Accessibility

Icons render with `role="img"`. Mark decorative icons with `aria-hidden="true"`; give meaningful icons an `aria-label` (or the `ariaLabel` prop) so assistive technology has a real name to announce.



---

# Affix

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


# Affix

Keep content fixed to the visible edge of the window or an actual scroll container after reaching an offset. The default slot accepts complete Vue content.

```vue
<Affix :offset-top="16" :target="() => scrollArea" @change="onAffixed">
  <button>Sticky toolbar</button>
</Affix>
```

## API

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| offsetTop | Top affixing offset | number | 0 when both offsets are absent |
| offsetBottom | Bottom offset. Top wins when both conditions match; bottom can still match when top does not | number | — |
| target | Actual scrolling element or Window. Omitted: Provider.getTargetContainer, then window | () => HTMLElement \| Window \| null \| undefined | — |
| prefixCls | Current component prefix | string | apollo-affix |

A null/undefined result means pending. It releases the previous target and fixed state without selecting window. Reactive template refs update automatically; use the existing `updatePosition()` method after a nonreactive target change.

| Event | Payload | Timing |
| --- | --- | --- |
| change | affixed: boolean | Accepted affixed state flips; unchanged scrolling does not repeat it |

| Slot | Description |
| --- | --- |
| default | Complete VNodeChild content with persistent node identity |

| AffixRef | Description |
| --- | --- |
| updatePosition(): void | Coalesce remeasurement of the current target and content into the next frame |

No new instance API is introduced. A template ref can use `ref<AffixRef | null>(null)`.

## Native attrs and current configuration

The outer measuring div owns native class/style, id, data, ARIA and listeners once. Vue merges string, array and object styles with `ConfigProvider.components.affix.style`; caller styles take precedence. These remain native attrs rather than Affix Props. The fixed and spacer nodes are internal positioning layers.

The prefix, component configuration and theme follow current Provider values. The sole component Token is `zIndexPopup`, derived from `zIndexBase + 10` by default. Replacement, removal and explicit zero affect the actual fixed layer.

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

## Geometry and cleanup

Existing rounded comparisons and the outer layout reference are preserved. Top has branch priority; setting it does not remove the bottom condition. Fixed width follows the outer available width. Content keeps its natural height, and its existing ResizeObserver updates the spacer on growth and shrinkage without replacing inputs.

Measurement and listeners start after mounting. Scroll listeners cover the current target, ancestors that move the target or placeholder, and the target's owner window. Top and bottom affixing follow the current target position when the outer page or a nested ancestor scrolls. Scrolling retains frame coalescing and the unchanged-position fast path; size notifications perform full measurement. Target replacement, a pending target and unmount release these listeners, observations and pending frames. SSR schedules none of these effects. Arbitrary position rearrangement without a size, scroll or explicit update signal does not add a new observer or polling loop.

## Demos

basic, offset-bottom, on-change, target and update-position. Existing geometry and s54 listener-idempotency regressions remain. Final nine-dimensional and distribution acceptance are separate.


## Basic (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 (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>
```

## Change callback (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>
```

## Container (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 (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


Show information that needs attention, with complete Vue content slots and an owned native close button. All15 working examples are in [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/alert/demo).

## Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| type | Alert type | `'success' \| 'info' \| 'warning' \| 'error'` | warning for banner, otherwise info |
| variant | Local value overrides current components.alert configuration | `'outlined' \| 'filled'` | outlined |
| title | Text title; use #title for rich content | `string` | — |
| message | Deprecated title alias, used when title is absent | `string` | — |
| description | Text description; use #description for rich content | `string` | — |
| showIcon | Explicit false suppresses the banner default icon | `boolean` | true for banner, otherwise false |
| banner | Banner appearance | `boolean` | false |
| closable | Boolean or close configuration; an object enables closing | `boolean \| AlertClosable` | current Provider, otherwise false |
| closeIcon | Legacy scalar icon; prefer #closeIcon or closable.closeIcon | `string \| number \| boolean \| null` | — |
| closeText | Deprecated close text; prefer #closeIcon | `string` | — |
| afterClose | Legacy completion callback; prefer @after-close | `() => void` | — |
| prefixCls | DOM prefix; preload matching static CSS for a custom prefix | `string` | apollo-alert |
| id / role | Actual root div attributes | `string` | role=alert |
| classNames / styles | root/icon/section/title/description/actions/close; object or function receiving current merged props | `AlertSemanticValue<…>` | — |

Native class/style, tabindex, ARIA/data, listeners and once modifiers belong to the actual root div. title remains the documented content prop. Native root listeners receive DOM events; onClick/onMouseenter/onMouseleave are their programmatic forms.

## Slots

| Slot | Description |
| --- | --- |
| #title | Complete title content; present empty content suppresses title/message fallback. |
| #description | Complete description; empty content removes description layout. |
| #icon | Complete type icon; empty slots suppress default artwork. showIcon=false takes precedence. |
| #action | Complete action content, including multiple native controls. |
| #closeIcon | Text/artwork inside the native close button; present empty slots suppress every icon fallback. |

All five slots are read in the current render and accept fragments and0. Conditional removal restores fallback. There is no implicit default-to-title API. Close content priority is slot, local configuration icon, closeText, legacy closeIcon, Provider configuration icon, Provider closeIcon, default artwork. Explicit0/false/null/empty strings are content values, not absent fields.

## Events and close state

| Event | Payload and timing |
| --- | --- |
| close | Native MouseEvent from click or Enter/Space activation; each instance accepts one close request. |
| after-close | Once after the owned alert completes removal, including disabled/reduced motion. |

onClose/onAfterClose are programmatic Vue listeners. Configuration onClose/afterClose hooks remain business notifications and cannot suppress Vue events; the same function is not called twice. A configured afterClose takes priority over the legacy plain callback. The button has the default accessible name Close; closable aria-label/aria-labelledby and data attributes belong to that button.

Closing is internal one-time state. There is no open/visible model or cancellation hook. Use parent v-if/key to remount; changing closable does not reopen a closed instance. Immediate parent removal during close does not report an internal animation completion. The existing truthy closeText shortcut remains ahead of the legacy boolean visibility branch.

## Ref

`AlertRef.nativeElement: HTMLDivElement | null` refers to the actual root and becomes null after removal/unmount.

## ErrorBoundary

Typed Alert.ErrorBoundary and named AlertErrorBoundary refer to the same component. Healthy default content remains a complete fragment without a wrapper. There is no reset method/model/expose; use parent key remounting for recovery.

| Prop | Description | Type |
| --- | --- | --- |
| title / message | Error title data; defaults to String(error), message is a legacy alias | `VNodeChild` |
| description | Error description; defaults to Vue error-phase information in pre | `VNodeChild` |
| id | Error fallback Alert id | `string` |

Vue onErrorCaptured handles actual descendant setup/render/lifecycle and owned event errors, including0/false/null/undefined, and stops propagation. The boundary itself and errors outside Vue's call chain are outside its scope. Native attrs/styles belong to the error fallback Alert; healthy fragment children do not receive arbitrary forwarded attrs.

The default Error details region is focusable and supports native horizontal keyboard scrolling on narrow screens. Custom description content owns its own interaction and semantics.

## Theme

| Token | Purpose | Default source |
| --- | --- | --- |
| borderRadius | Corner radius | borderRadiusLG |
| withDescriptionIconSize | Description icon size | fontSizeHeading3 |
| defaultPadding | Normal padding | paddingContentVerticalSM / fixed12px inline |
| withDescriptionPadding | Description padding | paddingMD / paddingContentHorizontalLG |

The nearest current theme.components.Alert and aliases are consumed on updates/removal. Explicit root CSS variables take precedence. Default/dark/compact/combined source scopes remain local; closing respects theme.token.motion and prefers-reduced-motion.

An explicitly empty ThemeProvider restores the default aliases and four component tokens, including through an unconfigured ConfigProvider. A ConfigProvider without any theme source leaves page CSS dark/compact scopes authoritative. Semantic functions receive the resolved type, variant, prefixCls, role, icon visibility and close state; role defaults to alert and accepts an explicit value.

Null or undefined Provider type icons retain the default fallback. Default icons are decorative; custom content owns its semantics.

Migration and validation boundaries: `docs/migrations/alert-contracts.md`, `docs/audit/2026-10-29-alert-contract-audit.md`.


## Basic (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>
```

## Four styles (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 (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 (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)

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

### 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)

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

### 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>
```

## Custom action (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 (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>
```

## Smoothly unload (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>
```

## Semantic styles (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 (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 (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 (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 slot precedence (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>
```

## Component tokens (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

Native links form a table of contents and track sections in the actual scrolling container. Items and default-slot composition share the same scrolling, indicator and Affix chain.

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

## Anchor Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| items | Recursive link data; a present default slot overrides it, including an empty slot | AnchorLinkItemProps[] | — |
| direction | Navigation arrangement | vertical \| horizontal | vertical |
| offsetTop | Affix top offset, wrapper maximum height and fallback scroll offset | number | — |
| bounds | Active-section tolerance | number | 5 |
| targetOffset | Scroll and detection offset, before offsetTop | number | — |
| affix | Use Affix; an object retains dynamic offsetBottom/prefixCls configuration | boolean \| AnchorAffixConfig | true |
| showInkInFixed | Show the indicator without Affix | boolean | false |
| getContainer | Actual scroll target; omitted: Provider.getTargetContainer, then window | () => HTMLElement \| Window \| null \| undefined | — |
| getCurrentAnchor | Pure highlight mapping; removal restores the raw href without changing event payloads | (activeLink: string) => string | — |
| replace | Use replaceState; link-level settings take precedence | boolean | false |
| prefixCls | Current component prefix and the default prefix of its Links | string | apollo-anchor |
| classNames | root/item/itemTitle/indicator classes or a function receiving { props } | AnchorSemanticClassNames \| function | — |
| styles | Corresponding Vue CSSProperties or a function receiving { props } | AnchorSemanticStyles \| function | — |

A null/undefined container is explicitly pending: it releases the old listener and active detection without selecting window. Reactive template refs, Provider replacement and offset changes synchronize the current chain.

## Owned events

| Component/event | Payload | Description |
| --- | --- | --- |
| Anchor change | currentActiveLink: string | The original href; highlight mapping does not change it |
| Anchor click | event: MouseEvent, link: AnchorLinkInfo | Before selection, scrolling and history operations |
| AnchorLink click | event: MouseEvent, link: AnchorLinkInfo | The same native event, before Anchor's aggregate notification |

Link info is `{ href, title }`, preserving full title content. Any click listener may preventDefault to cancel selection, scrolling and history. Notification uses emits once, without manually invoking listeners again. Templates use @click/@change; programmatic listeners retain onClick/onChange.

Modifiers, nonprimary buttons, download, new browsing contexts and external links keep native browser navigation. Plain same-document fragments resolve against their owning document and support native mouse and Enter activation. No extra arrow-key or focus model is introduced. Explicit replace uses replaceState for same-page fragments and retains location.replace for ordinary external URLs.

## Items, Link and slots

| Data field | Description |
| --- | --- |
| key | Required string/number business key in items |
| href | Required native link address |
| title | Required VNodeChild in items, including zero, empty values, arrays and components |
| target | Native a.target |
| className | Existing item/Link wrapper class |
| replace | Override the parent history behavior |
| targetOffset | Link-level scroll/detection offset, before component offsets |
| prefixCls | Explicit Link prefix |
| children | Recursive items only; horizontal navigation does not render nested links |

AnchorLink (also Anchor.Link) requires href. Its title data is optional so templates can use #title. There is no children prop; nested links use its default slot.

| Component/slot | Responsibility |
| --- | --- |
| Anchor default | Supported Vue composition; presence overrides items, including conditional empty content |
| AnchorLink title | Complete native anchor content; presence overrides title data even when empty or zero |
| AnchorLink default | Existing vertical nested-link composition |

Anchor and Link expose no public imperative control API or new v-model. Affix retains its own change event and updatePosition method.

## Native attrs, Provider and Tokens

Anchor native attrs/class/style belong to its wrapper, outside the inner navigation and inside Affix. Precedence is Provider, component semantic styles, then native attrs. Link class/style/data/id retain their item wrapper; aria-*, tabindex and native focus/keyboard listeners belong to the actionable a. Active links default to aria-current="location". Conditional contents, same-key item replacement and configuration updates preserve nodes and focus.

The current Provider prefix, direction, component configuration and theme remain reactive. Links inherit the current Anchor prefix unless explicitly overridden. Native dir lets logical CSS consume direction. The two component Tokens are linkPaddingBlock (paddingXXS by default) and linkPaddingInlineStart (padding); they project onto the actual consuming layer. Replacement, removal and explicit zero work, and existing aliases retain their derived roles.

## Resources and migration

Listeners start after mounting. New targets, changed configuration, container switches and unmount cancel stale scroll animations. Each link owns registration, so removing one duplicate href does not remove the others. The indicator tracks direction, content and actual sizes; observations and frames are released on unmount. SSR starts no browser effects. No position polling, router adapter or controlled-highlight model is added.

onClick/onChange are owned emits; the old claim that multiple arguments cannot be emitted is removed. Default composition no longer produces an upstream-derived deprecation warning. Replace the unused children prop with the default slot and use #title for content. A custom Anchor prefix now also owns its Links' default classes, keeping ink lookup consistent. The historical DOM baseline remains intact with exact prefix and native-dir differences.

## Demos

basic, horizontal, onChange, onClick, replace, target-offset, target-offset-per-link, customize-highlight, static, style-class, component-token and bounds. The Token demo uses real ConfigProvider.components.Anchor.


## Component 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)

通过 `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 Anchor (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>
```

## Semantic Styles (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)

Bind anchors to the adjacent scroll container. Click Section B/C or scroll its content to follow the active section.

### 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 changes the highlight only: Section B stays highlighted while links still scroll to their actual targets.

### 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 anchors control their own scroll area. Click a section or scroll to follow the bottom indicator.

### 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)

Scroll or click this demo’s anchors to inspect the change event. Targets belong to this demo only.

### 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)

Click an anchor to record its link information; scrolling and browser history retain their normal behavior. Call preventDefault() in the callback to intercept it.

### 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)

Use replaceState when clicking this demo’s anchors, so Back returns to the previous page rather than the previous anchor.

### 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)

Targets stop 60px below the scroll container’s top. targetOffset takes precedence over 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)

Set targetOffset per link and compare the 0, 120, and 60px landing positions.

### 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


Provide independent Message, Notification and Modal services to descendants, with shared root styles for the page.

## Demos

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/app/demo) for service usage and replacement of current message/notification defaults.

## API

| Prop | Description | Type | Default |
|---|---|---|---|
| prefixCls | Current host class prefix | `string` | `apollo-app` |
| component | Native host; `false` renders content and service holders without a host | `'div' \| 'section' \| 'main' \| 'span' \| false` | `'div'` |
| message | Message hook configuration, merged across nested Apps | `MessageConfigOptions` | — |
| notification | Notification hook configuration, merged across nested Apps | `NotificationConfig` | — |

The default slot accepts complete Vue content, including `0`, arrays, conditional and empty content. App has no owned events, v-model or imperative component ref methods. Native `class`, `style`, attributes and event listeners target the actual host. Provider `components.app.className/style` is merged first; local native styles take precedence.

With `component=false`, attributes have no host and produce a development diagnostic. They are not transferred to children or overlays. Host changes follow Vue's native subtree replacement rules; the three service holders remain stable siblings of the host.

### useApp

Call the named `useApp()` or `App.useApp()` in a **descendant component's setup**:

```ts
const { message, notification, modal } = App.useApp();
const close = message.loading('Working', 0);
close.then((terminated) => console.log(terminated));
const confirm = modal.confirm({ title: 'Continue?' });
confirm.then((accepted) => console.log(accepted));
```

The exact `UseAppProps` result contains `message: MessageInstance`, `notification: NotificationInstance` and `modal: ModalHookAPI`. Methods retain their hook's real return values and service callbacks. Commands issued during descendant setup enter the corresponding holder queues. Every App owns independent instances; nested consumers receive the closest provider. Unmounting App terminates its work and releases overlays and resources.

Without an App provider or Vue injection context, `useApp()` throws `[Apollo App] useApp() requires an App provider.` instead of returning empty fake APIs. Use a descendant's setup; the parent creating App cannot inject a child provider that does not yet exist.

### Configuration, theme and migration

Message and notification configurations are shallowly merged by field from parent App to local object. Local fields win. Replacing an object removes its former exclusive fields; removing a local prop restores the current parent configuration. The injected object retains its identity while descendants and holders read current values. Existing notices follow their respective service's update contract.

App has no component tokens. Its CSS consumes the global `colorText`, `fontSize`, `lineHeight` and `fontFamily` variables. Current Provider direction, prefix and root style replacement/removal update the host.

Replace the old documented `className/rootClassName` with native `class`; native `style` accepts StyleValue. AppConfig and useApp now expose actual configuration and service types. Type exports: `AppProps`, `AppComponentType`, `AppConfig`, `AppSlots`, `UseAppProps`.


## basic (basic)

Get instance for `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)

Configure `message` and `notification`. Switching defaults keeps the same App services.

### 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


A text input with selectable suggestions. The shared Select engine owns options, keyboard interaction, accessibility and theme behavior.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/auto-complete/demo). The basic example binds three models and demonstrates keyboard backfill; options support live conditional content.

## API

### Props

| Prop | Description | Type | Default |
|---|---|---|---|
| value / defaultValue | Controlled value / initial value; `v-model:value`, with raw values from typing and selection | `SelectValue` | — |
| searchValue | Search text; `v-model:search-value` | `string` | `''` |
| open / defaultOpen | Controlled popup / initial state; `v-model:open` | `boolean` | `false` |
| options | Suggestions; explicit `[]` also takes precedence over option slots | `DefaultOptionType[]` | — |
| dataSource | Deprecated text, `{ value, text? }`, or Option/OptGroup VNodes; existing conversion is retained | `DataSourceItemType[]` | — |
| placeholder | Placeholder text; rich content uses `#placeholder` | `string` | — |
| allowClear | Clear button, icon and accessible label configuration | `SelectProps['allowClear']` | `false` |
| disabled / size / variant / status | Shared Select state and appearance | — | — |
| showSearch | Search algorithms: `filterOption/filterSort/optionFilterProp/autoClearSearchValue` | `boolean \| SelectSearchConfig` | `true` |
| filterOption | Filter receives an actual option; `false` retains all suggestions | `boolean \| (text, option) => boolean` | — |
| defaultActiveFirstOption | Activate the first suggestion; `false` waits for keyboard or pointer activation | `boolean` | `true` |
| backfill | Preview keyboard candidates; Enter/Tab or a click commits, with no value/search notifications during preview | `boolean` | `false` |
| autoFocus / maxLength / id / tabIndex | Focus, text length, ID and Tab order of the actual input | — | — |
| listHeight / listItemHeight / virtual | Option dimensions and virtualization | same as Select | — |
| popupMatchSelectWidth / placement / getPopupContainer | Popup width, placement and container, including ShadowRoot | same as Select | — |
| classNames / styles | Object or `({ props }) => object`; semantic `root/prefix/input/placeholder/content/clear/popup.{root,list,listItem}` | — | — |

Controlled updates are proposals. Rejection retains the accepted value; releasing control retains the last accepted value. Keyboard backfill is a temporary preview. Pointer activation does not backfill. Accepted value changes, typing, actual closure, removing `backfill` or disabling the control clear the preview; reopening does not restore it. Numeric `0` is a valid option value.

Default slots are classified during render, preserving conditional slots, `v-if/v-for`, dynamic groups and existing option caching. Rich `dataSource` content remains data; top-level content extension uses slots. Replacing the input with a custom input/textarea remains unsupported and produces an explicit warning. AutoComplete has no public PurePanel entry.

### Events

| Event | Payload and behavior |
|---|---|
| change / update:value | `(value, option)` / `(value)`; typing, selection or clearing commits a value |
| search / update:searchValue | `(text: string)`; search notification / model proposal; selection synchronizes search, while derived external-value synchronization does not notify twice |
| select / deselect | `(value: string \| number, option)`; option selection; combobox has no multiple-selection removal action |
| openChange / update:open | `(open: boolean)`; notification and model proposal |
| focus / blur | `(event: FocusEvent)`; actual control focus |
| clear | Clear operation |
| popupScroll / inputKeyDown | `(event: Event)` / `(event: KeyboardEvent)` |

Notifications use typed emits. The `onSearch/onChange` fields accepted by `h()` are Vue listeners, not callback Props called manually. Replace `onDropdownVisibleChange` with `@openChange`; replace `showSearch.onSearch/searchValue/searchIcon` with `@search`, the top-level search model and `#searchIcon` respectively.

### Slots

`default` (Option/OptGroup data), `prefix`, `placeholder`, `notFoundContent`, `clearIcon`, `loadingIcon`, `searchIcon`, `labelRender="{ value, label }"`, `optionRender="{ option, index }"`, `popupRender="{ menu }"`, `menuItemSelectedIcon="{ value, disabled, isSelected }"`, and `suffixIcon="{ searchValue, open, focused, showSearch, loading }"`.

Slots forward dynamically. Empty content intentionally hides the result, and numeric `0` remains visible. There is no default arrow; `#searchIcon/#loadingIcon` can customize their corresponding state.

### Attrs, Provider and theme

Native `class/style/data-*` target the selector root; `id/tabindex/role/aria-*` target the actual input. Attrs are read during rendering, classes merge once, and string/array styles and removal remain current. Fallthrough cannot replace the owned combobox mode or notification handlers.

Current `components.autoComplete` classes, styles, semantics and search/clear configuration support replacement and removal. Select and AutoComplete component configuration remain isolated; the shared engine retains global size, direction, Form and Compact contexts. Both root and teleported popup use Select Tokens; AutoComplete has no separate tokens.

### Expose

| Member | Description |
|---|---|
| focus(options?: FocusOptions) / blur() | Operate on the actual input |
| scrollTo(arg?) | Number means a pixel coordinate; items use `{ index?, key?, align? }`; the existing `{ top }` coordinate form remains supported |
| nativeElement | Actual selector root, `HTMLElement \| null` |

Retained style aliases: `dropdownMatchSelectWidth` → `popupMatchSelectWidth`, `popupClassName/dropdownClassName` → `classNames.popup.root`, and `dropdownStyle` → `styles.popup.root`. Content functions use native slots such as `#popupRender`.


## Custom Options (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 (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 (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>
```

## Customize Render Panel (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` with custom clear icon.

### 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 combined with Select sharing the same 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)

Basic usage with controlled mode.

The second input binds all three models. With `backfill`, keyboard navigation previews a candidate; Enter/Tab or a click commits the value.

### 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)

Complete suggestions via `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)

Case-insensitive filtering via `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 via the `options` prop.

### 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)

Validation status.

### 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)

Semantic `classNames` / `styles` (object and function variants).

### 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)

Options follow the input value.

### 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)

Four variants.

### 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


Represent a person or object using an image, icon or characters. Static avatars do not enter the Tab order; use a native link or button for an action.

## Demos

Ten examples cover size/shape, content types, dynamic characters/gap, badges, groups, overflow counts, image fallback, hidden layouts, responsive sizes and current component tokens. The max-count example switches whether its visible budget includes the indicator; `max.count` itself always counts visible children only.

## Avatar Props

| Property | Description | Type | Default |
|---|---|---|---|
| prefixCls | Local component class prefix | `string` | current ConfigProvider |
| shape | Local shape overrides Group | `'circle' \| 'square'` | Group → `'circle'` |
| size | Local size overrides Group and global size; responsive maps use the largest matching configured breakpoint | `SizeType \| 'default' \| number \| ScreenSizeMap` | Group → componentSize → `'medium'` |
| gap | Horizontal space reserved when scaling default content, px | `number` | `4` |
| src | Image URL or complete VNode data; failures fall back to icon/default | `VNodeChild` | — |
| srcSet | Native image srcset; changing it retries the image | `string` | — |
| draggable | Native image draggable attribute | `boolean \| 'true' \| 'false'` | — |
| icon | Complete icon data | `VNodeChild` | — |
| alt | Native alternative; decorative by default, provide a name when identity matters | `string` | `''` |
| crossOrigin | Native image crossorigin | `'' \| 'anonymous' \| 'use-credentials'` | — |
| beforeFallback | Synchronous hook after error; return false to retain the failed image | `(event: Event) => boolean \| void` | — |

Native class/style/id, data/ARIA and other native listeners target the stable span root. String, array and object styles override size, theme and Provider styles. Default text is visible during SSR; root and content resize observation updates its scale after mounting.

## Slots / Events

| Slot | Content |
|---|---|
| image | Complete image content; its presence overrides src, including an intentionally empty slot |
| icon | Complete icon content when no image exists; its presence overrides icon data, including an empty slot |
| default | Characters or complete business content when no image/icon exists |

| Event | Payload | Behavior |
|---|---|---|
| click | native `MouseEvent` | Once per root click; merged listeners and `.once` work |
| error | native image `Event` | Once per image failure; listener return values do not cancel fallback, use beforeFallback |

## AvatarGroup / Avatar.Group

Both exports identify the same installable component.

| Property | Description | Type |
|---|---|---|
| prefixCls | Group class prefix | `string` |
| size | Current inherited size, including numbers, zero and responsive maps; children may override it | `AvatarSize` |
| shape | Inherited shape | `'circle' \| 'square'` |
| max | `{count?, style?, popover?}`: visible count, indicator style and Popover configuration | `AvatarGroupMax` |

`max.count` excludes the `+N` indicator. Zero, missing, negative and nonfinite counts are unlimited; positive fractions are floored. Direct default-slot children count after flattening Fragments and skipping comments. Render multiple avatars with a direct `v-for`; Group does not inspect a business component's internal output.

Overflow owns a native button. Default hover also supports click and Enter/Space; Escape closes while preserving button focus. Explicit focus triggers and controlled `max.popover.open` remain Popover configuration. `max.popover.content` may override popup content. Object/function classNames, styles, containers, triggers and open callbacks are forwarded; rootClassName adds a popup class. Hidden content is destroyed by default; `destroyOnHidden:false` preserves its state.

Native Group class/style/attrs target its div. Both components expose only nullable `nativeElement` (span/div). There is no avatar business model or additional instance method.

## Component Token

Configure current tokens through `ConfigProvider :theme="{components:{Avatar:{…}}}"`. Source replacement/removal, nested Providers and all four algorithms apply to each avatar and overflow content. Native style variables override their owning root.

| Token | Type | Default source |
|---|---|---|
| containerSize / containerSizeLG / containerSizeSM | `number` | controlHeight / controlHeightLG / controlHeightSM |
| textFontSize / textFontSizeLG / textFontSizeSM | `number` | fontSize |
| iconFontSize / iconFontSizeSM | `number` | average icon size / fontSize |
| iconFontSizeLG | `number \| string` | fontSizeHeading3 |
| groupSpace | `number` | marginXXS |
| groupOverlapping | `number`, may be negative | -marginXS |
| groupBorderColor | `string` | colorBorderBg |

See the [Avatar migration notes](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/avatar-contracts.md) for development-stage event and Group alias changes.


## Basic (basic)

Five sizes and circle/square shapes, with complete icon VNode data.

### 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 (type)

Images, complete VNodes, custom colours, characters and icons. Pair foreground and background colours.

### 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>
```

## Autoset Font Size (dynamic)

Switch names, colours and gap; text refits its current size.

### 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>
```

## With Badge (badge)

Combine badges and avatars.

### 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>
```

## Avatar.Group (group)

Combine avatars, a link and Tooltip. max.count counts visible children; the overflow button is additional.

### 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 includes overflow (max-count)

Render direct v-for children. The switch changes the demo budget: two visible items plus the indicator, or three plus the indicator; it does not redefine 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 (fallback)

Invalid local image data triggers error and falls back to characters. Custom image VNodes own their image error handling.

### 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>
```

## Compute alignment when hidden (toggle-debug)

Toggle visibility, avatar size and outer visual scaling to verify measurement after showing.

### 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 size (responsive)

Use the largest matching configured breakpoint, with visible text to inspect the size.

### 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>
```

## Current component tokens (component-token)

Change the twelve existing Avatar tokens through the current ConfigProvider. Toggle the override off to restore inherited values. Open overflow with a pointer or Enter/Space to inspect hidden avatar spacing.

### 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


A button to scroll back to top.

> ⚠️ Deprecated since antd 6.x. Use `FloatButton.BackTop` instead.

## API

| Prop | Description | Type | Default |
|---|---|---|---|
| visibilityHeight | Show after scrolling past this value (px) | `number` | `400` |
| duration | Scroll-to-top duration (ms; <=0 jumps directly) | `number` | `450` |
| target | Reactive container getter; supports pending template refs | `() => HTMLElement \| Window \| Document \| null` | `ownerDocument` |
| prefixCls | Component class prefix | `string` | `apollo-back-top` |

The `click` event emits the original `MouseEvent` once after scrolling starts; use `@click` or `onClick` with `h()`. Vue `.once` works normally.
The default slot accepts complete text, numbers, sibling nodes and Fragments. An explicitly empty slot hides the button; an absent slot uses the default icon. Slot VNodes are preserved inside a stable `-custom` span.

`nativeElement` exposes the actual `HTMLButtonElement | null`. The root is a native `type="button"` control with Tab, Enter, Space and focus styles. Hidden controls are excluded from keyboard navigation. Native class, style, ARIA, data attributes and listeners belong to this button. Its default icon label is “Back to top”; use `aria-label` to localize it. Give custom icon content an accessible name and keep nested interactive controls outside the slot.

Current `ConfigProvider.components['back-top'].className/style` apply to the root; native style wins. `theme.components.BackTop.zIndexPopup` defaults to `zIndexBase + 10`. Theme `motion: false` and the system reduced-motion preference disable scrolling animation.

## Design Notes

- `visibilityHeight={0}` keeps it always visible.
- The responsive inset narrows at viewports <= 768px / <= 480px.
- Changing targets, clicking again or unmounting cancels the previous scroll animation. Container listeners and pending scroll frames are released on target changes and unmount.

## Development migration (2026-10-30)

Under ADR 0007, the old root `div` becomes a native button, default content uses spans, and custom content gains a stable span host. Update tag selectors and move nested buttons/links outside the slot. Existing component classes remain available. The default slot now renders all nodes instead of cloning its first child. This development correction has no compatibility adapter or deprecation period; original reference baselines remain unchanged with exact differences asserted by this component's tests.


## Basic (basic)

Scroll the content past 100px to reveal the button. The target getter follows the template ref, and `@click` receives the native click event. The control stays inside the demo container and reports completed activations. (Deprecated — use `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


A small status descriptor for UI elements.

## When To Use

- Displayed at the top-right of icons or avatars to indicate messages or items needing attention.
- The count can be a number, text, or a red dot.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/badge/demo) (13 demos, including numeric counts and rich template content).

## API

### Badge

| Prop | Description | Type | Default |
|---|---|---|---|
| prefixCls | DOM prefix; custom prefixes need author-provided CSS | `string` | `apollo-badge` |
| scrollNumberPrefixCls | Digit track prefix | `string` | `apollo-scroll-number` |
| count | Number to display (`null` hides; overflow shows `+`) | `VNodeChild` | `null` |
| overflowCount | Max count | `number` | `99` |
| dot | Show a dot, overriding count including zero | `boolean` | `false` |
| showZero | Show when value is 0 | `boolean` | `false` |
| size | Size (`default` deprecated, equals `medium`) | `'medium' \| 'small'` | `'medium'` |
| status | Status dot | `'success' \| 'processing' \| 'error' \| 'default' \| 'warning'` | — |
| color | Custom color | `string` | — |
| text | Status text | `VNodeChild` | — |
| title | Native title (`null`/`false` disables; falls back to count) | `string \| null \| false` | — |
| offset | Offset `[x, y]` | `[number \| string, number \| string]` | — |
| classNames / styles | Root and indicator semantics; object or props function | — | — |

Native Vue class/style, id, ARIA, tabindex and listeners belong to the root span. Style accepts objects, strings and arrays; use styles.indicator for the indicator. Badge declares no business emits or v-model. Changing status/count retains the root and its focus. Independent text=0 does not hide a nonzero count. Explicit title also applies to standalone status indicators; null/false disables it.

Non-scalar counts (VNode, arrays, Fragments, text nodes and multiple-root components) share a native indicator and complete rendering with #count. Business nodes retain their attributes and identity; semantic styles/classes, title and offset belong to the indicator. Vue-empty counts create no empty badge and do not hide independent captions. An empty conditional component hides its host without remounting the business instance.

### Badge Slots

| Slot | Description |
| --- | --- |
| default | Content wrapped by the badge |
| count | Static rich indicator; overrides the count prop without overflow or digit rolling |
| text | Rich status text; overrides the text prop |

Slot presence determines precedence, including empty results. Removing a conditional slot restores its prop. Text `0` in #count is static content; showZero and overflowCount apply to numeric props. Dot mode overrides both count channels. Rich indicators retain indicator styles, offset and their previous visible content while leaving. VNodes do not generate an automatic title. Use the count prop for digit animation.

### Badge.Ribbon

| Prop | Description | Type | Default |
|---|---|---|---|
| prefixCls | DOM prefix | `string` | `apollo-ribbon` |
| className | Existing independent indicator class; use native class for the wrapper | `string` | — |
| text | Ribbon text | `VNodeChild` | — |
| color | Color | `string` | — |
| placement | Placement corner | `'start' \| 'end'` | `'end'` |
| classNames / styles | Root, indicator and content semantics; object or props function | — | — |

Ribbon default wraps business content. Its #text accepts complete content, with presence taking priority even when empty; removing the slot restores the text prop. VNodeChild arrays, Fragments and zero render normally. Native attrs/class/style belong to the wrapper; styles.indicator/content target the ribbon and its text.

### Expose and current configuration

BadgeRef and RibbonRef expose readonly nativeElement: HTMLElement|null, pointing to the actual current root and clearing on unmount. ConfigProvider.components.badge/ribbon, direction and prefix remain reactive, including replacing/removing semantic objects or functions. Provider style is a separate configuration field: Badge standalone status targets root, other Badge modes target indicator; Ribbon targets indicator. Use semantic styles for an explicit region.

## Theme

### Component Token

9 tokens: `indicatorZIndex`, `indicatorHeight`, `indicatorHeightSM`, `dotSize`,
`textFontSize`, `textFontSizeSM`, `textFontWeight`, `statusSize`, `paddingInline`.

Values derive from current aliases and consume theme.components.Badge, including applicable zero values, replacement and removal. Explicit root CSS variables win. textFontSize/textFontSizeSM/textFontWeight apply to counts. Small digit tracks use the actual small height. Reduced-motion disables ripple, digit transitions and enter/leave motion.

Opaque count/ribbon backgrounds select readable foregrounds while preserving preset backgrounds. Explicit semantic text colors win; authors pair foregrounds with custom gradients, alpha backgrounds or complete style overrides. Extra animation digits are hidden from accessibility; no live region is created automatically. Negative integers keep their sign. Numeric offsets use px, while CSS lengths, percentages and expressions retain their units.

See the [development migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/badge-contracts.md) for native root style, complete content and reference fixes. Original reference HTML/PNGs remain evidence, not the specification of Vue usage.


## Basic (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>
```

## Standalone (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 Count (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>
```

## Red badge (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>
```

## Dynamic (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>
```

## Clickable (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 (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)

`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 (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 (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 (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>
```

## Semantic style & class (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>
```

## Template content and numeric counts (content-slots)

`#count` renders static rich content without numeric overflow or digit rolling. Use the count prop for animated numbers. Badge and Ribbon #text accept complete rich content. A present slot overrides its prop, including empty content; removing the slot restores the prop. Dot mode takes precedence, including zero counts. Leaving indicators retain their last visible content and both business inputs stay mounted.

### 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


A decorative light beam flowing along an HTML container's border.

## API

| Prop | Description | Type | Default |
|---|---|---|---|
| prefixCls | Full effect class and runtime CSS variable prefix | `string` | Provider prefix + `-border-beam` |
| color | Solid color or gradient stops (0–100 mapped to 0–70%) | `string \| { color: string; percent: number }[]` | Theme primary gradient |
| count | Finite values ≥1 are rounded down; other values use 1 | `number` | `1` |
| duration | Finite, positive seconds per revolution; other values use 6 | `number` | `6` |
| lineWidth | Beam thickness; numbers use px | `number \| string` | Theme `lineWidth` |
| outset | Uniform inset offset; otherwise follows each host border width | `number \| string` | — |
| size | Beam head length; numbers use px | `number \| string` | `100px` |
| classNames.effect | Class on each decorative effect div | `{ effect?: string }` | — |
| styles.effect | Inline style on each decorative effect div | `{ effect?: CSSProperties }` | — |

## Slots and native attrs

The default slot accepts `VNodeChild`. One HTML root is decorated, including a component's conditional or asynchronously resolved single root. Comments, whitespace and single-root Fragments preserve the host. Text, SVG and multiple meaningful roots remain complete and receive no effect. There is no extra layout container.

Native `class`, `style`, `data-*`, `aria-*` and listeners merge into the selected host VNode using Vue semantics. The host's own styles take precedence for overlapping properties; component hosts follow their normal attrs forwarding rules. Original keys, template refs, ref arrays, named slots and lifecycle hooks remain owned by their caller. Take a template ref on the child to access its element or component; BorderBeam has no public methods, events or model.

The host supplies its positioning context, usually `position: relative`. Effects inherit its border radius, ignore pointer events and are `aria-hidden`. Runtime effect variables merge before Provider `style`, Provider `styles.effect`, then component `styles.effect`; the latter wins. Provider `className` and `classNames.effect` remain effect configuration.

A visible host's border widths are sampled on one shared 500ms clock, using that host's document. Hidden documents skip style reads and refresh when visible. No HTML hosts means no sampler subscription; host replacement, document adoption and unmount release their resources. SSR preserves content and creates no effects or timers. Reduced motion hides the beam.

## Migration

Component `className` and effect-targeting `style` Props have been removed. Use native `class`/`style` for the host and `classNames.effect`/`styles.effect` for the decorative layer. If Vue replaces the host's text content, its removed decoration is recreated while the host's identity and focus remain intact.


## Basic (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 (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>
```

## Multiple beams (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 (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>
```

## Gradient color (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` 控制单圈时长（秒）。

### 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` 控制流光头部长度。

### 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 (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


Shows the current page in a hierarchy and provides upward navigation. Use data items or compose `BreadcrumbItem` / `BreadcrumbSeparator` in the default slot.

## Examples

`demo/` contains 11 paired examples covering navigation, icons, parameters, menus, separators, native children, scoped content, semantic styles and theme variables. `debug-routes` demonstrates migration of legacy route data.

## API

### Breadcrumb

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| items | Data source; a provided `[]` stays empty and does not evaluate the default slot | `BreadcrumbItemInput[]` | — |
| routes | Deprecated legacy data channel; use items | `BreadcrumbItemInput[]` | — |
| params | Replaces complete `:key` names in string titles/paths; supports repeated names, zero and empty strings; missing/null values preserve placeholders | `Record<string, unknown>` | `{}` |
| separator | Automatic separator; slot first, then prop → current Provider → default | `VNodeChild` | `/` |
| dropdownIcon | Decorative menu button icon; slot first, then prop → current Provider → default | `VNodeChild` | `DownOutlined` |
| prefixCls | Current prefix of this navigation and its owned Item/Separator nodes; custom prefixes require matching static CSS | `string` | `apollo-breadcrumb` |
| classNames | root/item/separator classes; functions receive current resolved props | `BreadcrumbSemanticClassNames \| ((info: { props: BreadcrumbProps }) => BreadcrumbSemanticClassNames)` | — |
| styles | Styles for the same semantic regions; functions receive current resolved props | `BreadcrumbSemanticStyles \| ((info: { props: BreadcrumbProps }) => BreadcrumbSemanticStyles)` | — |

Native class/style, id, ARIA/data attrs and listeners belong to the root nav. Native style overrides semantic styles and theme variables. Provider `components.breadcrumb` supports className, style, classNames, styles, separator and dropdownIcon, using current values. Breadcrumb has no component event or model; it exposes `nativeElement: HTMLElement | null`.

| Slot | Scope | Behavior |
| --- | --- | --- |
| default | — | Native children, only when neither items nor routes is provided; retains caller keys |
| itemRender | `{ route, params, routes, paths, href }` | Replaces a data item's default content; paths/href belong to that item |
| separator | — | Replaces automatic separators |
| dropdownIcon | — | Replaces the decorative menu button icon |

A present slot wins, including intentionally empty content. Conditional slots update and restore prop/default content when removed. The last item has no automatic separator. Custom itemRender content goes into a stable host; callers own its links, ARIA, listeners and styles.

### Data items

`BreadcrumbItemInput = Partial<BreadcrumbItemType & BreadcrumbSeparatorType>`.

| Field | Description | Type |
| --- | --- | --- |
| key | Business identity; defaults to index; provide stable keys when reordering | `string \| number` |
| title | Complete Vue content; only strings substitute parameters | `VNodeChild` |
| href | Direct destination | `string` |
| path | Accumulates this and previous path segments as `#/a/b`; takes precedence over href | `string` |
| className / style | Classes and effective inline styles of the default link/text/action button | `string` / `CSSProperties` |
| onClick | Native click on default content; an item without href uses a native button | `(event: MouseEvent) => void` |
| `aria-*` / `data-*` | Attributes of default content | — |
| menu | Menu items and Menu configuration | `BreadcrumbItemMenu` |
| dropdownProps | Dropdown configuration; controlled state uses open/onOpenChange | `DropdownProps` |
| breadcrumbName / children | Deprecated legacy routes title/one-level menu conversion | `string` / `Omit<BreadcrumbItemType, 'children'>[]` |
| type / separator | `type: 'separator'` creates an independent decorative separator and does not accumulate a path | `'separator'` / `VNodeChild` |

Menu items support key, label/title, href, path, and Menu's disabled, icon, extra and business event fields. Explicit href wins; otherwise path appends to the current breadcrumb href, or is used directly without a base. A provided label, including empty content, takes precedence over title.

### BreadcrumbItem / BreadcrumbSeparator

BreadcrumbItem supports href, menu, dropdownProps, dropdownIcon, separator and prefixCls. The default slot supplies complete content; #separator and #dropdownIcon override local props and then fall back to the owning Breadcrumb's current values. Native class/style, id, ARIA/data attrs and listeners belong to the owning li. @click receives one native MouseEvent. The final item's automatic separator is suppressed.

BreadcrumbSeparator has a default content slot and native attrs on its decorative `<li aria-hidden="true">`. No slot renders `/`; a present empty slot stays empty. Prefix and semantic styles come from its owning Breadcrumb. Attributes cannot expose decorative content to assistive technology. Both children are supported without component deprecation warnings and have no extra expose or model.

### Menu keyboard and focus

The navigation link and menu button are siblings. The named native menu button supports pointer, Enter, Space and ArrowDown opening. Keyboard opening moves focus into the menu, which owns its arrow-key behavior. Escape requests closing. Accepted closing returns focus only when it still belongs to that menu; controlled refusal and external focus retain their owner. Default trigger actions are hover/click on the arrow button. dropdownProps.trigger can customize pointer behavior while native keyboard access remains available.

## Design Token

Current themes, dark/compact algorithms, nested Providers and runtime replacements apply root CSS variables. Native style may override them.

| Token | Default source | Consumer |
| --- | --- | --- |
| itemColor | colorTextSecondary | Ordinary text |
| lastItemColor | colorText | Final item text |
| linkColor | colorTextSecondary | Default link/action button |
| linkHoverColor | colorText | Link/menu area hover |
| iconFontSize | fontSize | Apollo icons in content; dropdown arrow uses fontSizeIcon |
| separatorColor | colorTextDescription | Decorative separator |
| separatorMargin | marginXS | Separator inline margins |

See [Breadcrumb contract migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/breadcrumb-contracts.md).


## Basic (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` 覆盖默认的 `/`。

### 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 (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 an Icon (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 (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>
```

## With Dropdown (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>
```

## Deprecated 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 composition and current content slots (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>
```

## Native scoped items and children (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>
```

## Component 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>
```

## Semantic styles (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


A button triggers an action or navigates through a native anchor.

## When To Use

Use a button to submit a form, confirm an operation or trigger an action. Use `href` for navigation through a native link.

## Examples

All 20 original demos remain: `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

| Property | Description | Type | Default |
|---|---|---|---|
| type | Visual shorthand; color/variant independently override it | `ButtonType` | 'default' |
| color | Independent semantic or preset color | `ButtonColorType` | — |
| variant | Independent visual variant | `ButtonVariantType` | — |
| icon | Icon data or Vue component; #icon takes precedence | `ButtonIcon` | — |
| iconPosition | Existing deprecated alias; use iconPlacement | `ButtonIconPlacement` | — |
| iconPlacement | Icon position, ahead of the existing alias | `ButtonIconPlacement` | 'start' |
| shape | Shape; square has zero corner radius | `ButtonShape` | 'default' |
| size | Size: local, Compact, then Provider | `ButtonSize` | — |
| disabled | Disabled; explicit false overrides inherited true | `boolean` | — |
| loading | Immediately blocks activation; delay postpones the indicator | `ButtonLoading` | false |
| prefixCls | Root class prefix | `string` | apollo-btn |
| ghost | Transparent background; solid maps to outlined | `boolean` | false |
| danger | Danger color shorthand, below explicit color | `boolean` | false |
| block | Full container width | `boolean` | false |
| href | Defined renders an anchor, including an empty string | `string` | — |
| htmlType | Native button type | `ButtonHTMLType` | 'button' |
| autoInsertSpace | Visual spacing for two Chinese characters; original text is retained | `boolean` | true |
| classNames | Object classes for root/icon/content | `ButtonSemanticClassNames` | — |
| styles | Object styles for 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 }`.

### Current configuration and native attributes

Each explicit color/variant wins independently, followed by type/danger shorthand, then current Provider values. Without a color, solid uses primary; other variants use default. Ghost maps solid to outlined. Provider replacement, removal and restoration use current values.

Vue class and all native style forms merge onto the real button/anchor root. Native style wins over semantic root style and source tokens. Native events and form attributes retain their normal behavior. Enabled anchors respect caller tabindex; disabled anchors lose href and force tabindex=-1. Prefixes require matching static CSS; genButtonStyle('my-app') generates .my-app-btn styles.

### Slots

| Name | Content |
|---|---|
| default | Complete Vue content; comments and empty fragments do not create an empty host |
| icon | Complete Vue icon content, before icon data; an intentionally empty slot hides the fallback |

The owned .apollo-btn-content receives content classes/styles. Business child VNodes, text, state and refs remain intact. Chinese spacing uses CSS and preserves the accessible text. Semantics accept objects; function forms are not part of this API.

### Emits and ref

click emits one native MouseEvent. Disabled or requested loading prevents activation/default submission and propagation; the pending delay already blocks click. Loading retains focus and exposes aria-busy/aria-disabled. Only the indicator waits for a finite positive delay; cancellation/unmount clears it, icon replacement does not restart it, and SSR creates no delay timer. Owned loading graphics are decorative. Give icon-only buttons an accessible name through aria-label.

The only expose is nativeElement: HTMLButtonElement | HTMLAnchorElement | null, including null before mount/after unmount. There is no v-model or additional focus/blur service.

### Component tokens and exports

All 45 explicit fields below and the 13 existing preset shadow fields are consumed by current theme.components.Button. Native root variables win, such as --apollo-btn-content-font-size. Numeric lengths use px; font weight and line-height remain unitless. Finite nonnegative sizes, including zero, are retained; invalid numeric sizes fall back. Removing source configuration restores inherited/static defaults.

| Token | Target |
|---|---|
| fontWeight | Font weight |
| iconGap | Icon/content gap |
| defaultShadow | Shadow |
| primaryShadow | Shadow |
| dangerShadow | Shadow |
| primaryColor | Primary solid text in all three states; defaults to colorTextLightSolid (white) |
| defaultColor | Corresponding color/state foreground, background or border |
| defaultBg | Corresponding color/state foreground, background or border |
| defaultBorderColor | Corresponding color/state foreground, background or border |
| dangerColor | Danger solid text in all three states; defaults to colorTextLightSolid (white) |
| defaultHoverBg | Corresponding color/state foreground, background or border |
| defaultHoverColor | Corresponding color/state foreground, background or border |
| defaultHoverBorderColor | Corresponding color/state foreground, background or border |
| defaultActiveBg | Corresponding color/state foreground, background or border |
| defaultActiveColor | Corresponding color/state foreground, background or border |
| defaultActiveBorderColor | Corresponding color/state foreground, background or border |
| borderColorDisabled | Corresponding color/state foreground, background or border |
| defaultBorderColorDisabled | Corresponding color/state foreground, background or border |
| groupBorderColor | Group/Compact seams |
| defaultGhostColor | Corresponding color/state foreground, background or border |
| ghostBg | Corresponding color/state foreground, background or border |
| defaultGhostBorderColor | Corresponding color/state foreground, background or border |
| solidTextColor | Explicit default/preset solid text; does not override primaryColor/dangerColor |
| textTextColor | Corresponding color/state foreground, background or border |
| textTextHoverColor | Corresponding color/state foreground, background or border |
| textTextActiveColor | Corresponding color/state foreground, background or border |
| paddingInline | Size-specific padding |
| paddingInlineLG | Size-specific padding |
| paddingInlineSM | Size-specific padding |
| paddingBlock | Size-specific padding |
| paddingBlockLG | Size-specific padding |
| paddingBlockSM | Size-specific padding |
| onlyIconSize | Icon-only size |
| onlyIconSizeLG | Icon-only size |
| onlyIconSizeSM | Icon-only size |
| linkHoverBg | Corresponding color/state foreground, background or border |
| textHoverBg | Corresponding color/state foreground, background or border |
| contentFontSize | Size-specific font size |
| contentFontSizeLG | Size-specific font size |
| contentFontSizeSM | Size-specific font size |
| contentLineHeight | Size-specific line height |
| contentLineHeightLG | Size-specific line height |
| contentLineHeightSM | Size-specific line height |
| defaultBgDisabled | Corresponding color/state foreground, background or border |
| dashedBgDisabled | Corresponding color/state foreground, background or border |

Preset shadows: `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>
```

Primary and danger solid buttons use colorTextLightSolid in normal, hover and active states; automatic black/white selection does not replace these foregrounds. Browsers supporting relative colors limit excessive luminance of these solid backgrounds to keep default white text readable without changing global Alias values. Default/preset solid buttons retain automatic foregrounds, and colored text retains native CSS lightness correction. Explicit foreground tokens and native styles win; authors pair custom text, transparent and gradient surfaces with suitable backgrounds. Unsupported functions retain the Alias fallback; actual browser coverage is recorded in the audit.

Button, genButtonStyle and prepareButtonComponentToken are exported from @apollo-design/ui and @apollo-design/ui/button. Types include ButtonProps, ButtonRef, ButtonSlots, ButtonSlot, ButtonConfig, the enums/semantic types above, ButtonComponentToken and ButtonTokenInput. The old documented button/style/token path is not a package export.

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

[Contract migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/button-contracts.md).


## Type (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)

`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)

`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)

⚠️ 两个分支的 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)

`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)

幽灵按钮把背景变透明，常用在有色背景上。

⚠️ `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` 让按钮撑满父容器宽度（`-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)

`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)

`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 and variant (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)

传了 `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>
```

## Semantic (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>
```

## Component 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>
```

## Chinese Chars 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 (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 (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 Background (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 (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 (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 (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


Display and select dates using an inline month or year panel.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/calendar/demo) for nine examples, including native header/cell slots and current component tokens.

## API

### Props

| Property | Description | Type | Default |
|---|---|---|---|
| value | Accepted date (`v-model:value`) | `CalendarDate` (Dayjs) | — |
| defaultValue | Initial uncontrolled date; later changes do not reset state | `CalendarDate` | Today |
| mode | Accepted panel mode (`v-model:mode`) | `'month' \| 'year'` | `'month'` |
| fullscreen | Full calendar; false uses a compact card | `boolean` | `true` |
| showWeek | Show week numbers | `boolean` | `false` |
| validRange | Inclusive selectable bounds | `[CalendarDate, CalendarDate]` | — |
| disabledDate | Additional disabled predicate, OR-ed with the range | `(date: CalendarDate) => boolean` | — |
| locale | Deep merge with the current `ConfigProvider.locale.Calendar` | `PickerLocale` | Current locale |
| classNames | Six semantic targets; object or current-props function | `CalendarSemanticValue<CalendarSemanticClassNames, CalendarProps>` | — |
| styles | Six semantic targets; object or current-props function | `CalendarSemanticValue<CalendarSemanticStyles, CalendarProps>` | — |
| prefixCls | Picker class prefix | `string` | Current root prefix + `-picker` |

Native `class`, all Vue `style` forms, id, ARIA/data attrs, tabindex and ordinary DOM listeners reach the actual root div. Native style follows theme/Provider/local semantic style. Owned notification listeners are consumed by Vue emits.

Controlled models emit proposals. Rejected proposals do not become hidden local state; removing control preserves the last accepted value/mode. Defaults only initialize uncontrolled state.

### Slots

| Slot | Scope | Behavior |
|---|---|---|
| `headerRender` | `{ value, type, onChange, onTypeChange }` (`CalendarHeaderRenderConfig`) | Replace the header. The two commands request a date/mode change through the normal Calendar path. |
| `cellRender` | `{ current, info }` (`CalendarCellSlotProps`) | Content below the default date/month label. |
| `fullCellRender` | `{ current, info }` (`CalendarCellSlotProps`) | Replace the complete cell, including its label. Takes precedence over `cellRender`. |

`current` is a Dayjs date; `info` is the existing `CalendarCellRenderInfo` from PickerPanel, including `type`, `locale` and `originNode`. Slots are read during render, so conditional addition/removal works. Arrays, text, 0 and explicit empty content keep their Vue meanings.

```vue
<Calendar v-model:value="date" v-model:mode="mode">
  <template #headerRender="{ value, type, onChange, onTypeChange }">
    <button @click="onChange(value.add(1, 'month'))">Next month</button>
    <button @click="onTypeChange(type === 'month' ? 'year' : 'month')">{{ type }}</button>
  </template>
  <template #cellRender="{ current }">{{ events[current.format('YYYY-MM-DD')] }}</template>
</Calendar>
```

Migration: `headerRender`, `cellRender`, `fullCellRender` content props and the four legacy date/month content props are removed. Use the named slots directly. Split date/month content using `info.type`. There is no fallback callback or deprecation channel; `disabledDate` remains a genuine predicate service.

### Events

| Event | Payload |
|---|---|
| `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' })` |

Date requests emit `update:value`, then `panelChange` when crossing a month in month mode or a year in year mode, then `change`, then `select`. The same day only emits `select`. Mode requests emit `update:mode` only when different, then `panelChange` with the current date. The panel's select source is `date` or `month`; header date commands use `customize`.

### Ref

`nativeElement: HTMLDivElement | null` is the actual root and becomes null on unmount. Calendar exposes no imperative focus/blur methods. Its panel and controls retain their own native keyboard/focus behavior.

## Presentation and theme

Semantic targets are `root`, `header`, `body`, `content`, `item`, `itemContent`. The last four reach PickerPanel; `itemContent` also decorates Calendar's default content container. Semantic functions read current public props; fullscreen is resolved (default true), mode remains the raw prop. Returning undefined contributes no override.

`ConfigProvider.components.calendar` supplies presentation defaults. `ConfigProvider.theme.components.Calendar` supplies the six component tokens; replacement/removal updates existing instances.

| Token | Type | Default |
|---|---|---|
| fullBg | string | colorBgContainer |
| fullPanelBg | string | colorBgContainer |
| itemActiveBg | string | controlItemBgActive |
| yearControlWidth | number or CSS length string | 80 |
| monthControlWidth | number or CSS length string | 70 |
| miniContentHeight | number or CSS length string | 256 |

Numeric lengths become px, including 0. Static CSS and the existing 21 shared panel declarations remain in use; class and variable namespaces differ (`apollo-picker-calendar` versus `--apollo-calendar-*`). Custom class prefixes require the matching generated stylesheet.


## Basic (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)

用于嵌套在空间有限的容器中。

### 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)

自定义日历头部内容。

### 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 (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 (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)

受控用法：`@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 (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>
```

## Show Week (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>
```

## Component 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


A general card container.

## When To Use

- The most basic card container. It can host text, lists, images and paragraphs —
  commonly used on dashboard pages.
- When a group of related information should be grouped in one container and
  visually separated from its surroundings.

## Demos

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/card/demo) (**12**, matching antd's user-visible demos).

| demo | Content |
|---|---|
| `basic` | Typical card (with a `size="small"` counterpart) |
| `border-less` | Borderless card via `variant="borderless"` |
| `simple` | Content area only (no head) |
| `flexible-content` | `cover` + `Card.Meta` |
| `in-column` | Used together with grid columns |
| `loading` | `loading` renders a Skeleton inside the body |
| `grid-card` | Content separation via `Card.Grid` |
| `inner` | Inner card via `type="inner"` |
| `tabs` | Card with tabs via `tabList` |
| `meta` | Cover + avatar + title + description |

The current twelve Demos include style-class and component-token. Historical counts and gaps retain their original dates in README.

## API

### Card

| Property | Description | Type | Default | Global Config |
|---|---|---|---|---|
| title | Card title | `VNodeChild` | — | × |
| extra | Content to render in the top-right corner | `VNodeChild` | — | × |
| cover | Cover content | `VNodeChild` | — | × |
| actions | Action list (each wrapped in `<li><span>` with equal widths) | `VNodeChild[]` | — | × |
| loading | Show a Skeleton instead of the content | `boolean` | `false` | × |
| hoverable | Lift the card on hover | `boolean` | `false` | × |
| size | Card size | `'medium' \| 'small' \| 'middle' \| 'default'` | `medium` | ✅ (`componentSize`) |
| type | Card type (only `'inner'` for now) | `'inner'` | — | × |
| variant | Variant. `'borderless'` drops `-bordered` and uses the tertiary shadow | `'outlined' \| 'borderless'` | `outlined` | ✅ (`card.variant`) |
| tabList | Tab list. ⚠️ `tab` is deprecated, use `label` | `CardTabListType[]` | — | × |
| activeTabKey | Current tab; supports v-model:active-tab-key and release to the last accepted value | `string` | — | × |
| defaultActiveTabKey | Initial active tab (uncontrolled) | `string` | — | × |
| tabBarExtraContent | Extra content on the tab bar | `VNodeChild \| { left, right }` | — | × |
| tabProps | Props forwarded to the internal `Tabs` | `TabsProps` | — | × |
| classNames | Semantic class names (7 slots), function form supported | `CardSemanticClassNames \| ((info) => …)` | — | ✅ (`card.classNames`) |
| styles | Semantic styles (7 slots), function form supported | `CardSemanticStyles \| ((info) => …)` | — | ✅ (`card.styles`) |
| prefixCls | Class prefix (**the root prefix itself**, not a suffix) | `string` | from ConfigProvider, falls back to `apollo-card` | × |
| class / style | **Native root attrs** (not Props) | `string \| array \| object` / `CSSProperties` | — | × |
| id | Root element id | `string` | — | × |
| bordered | ⚠️ **Deprecated**, use `variant` | `boolean` | — | × |
| headStyle | ⚠️ **Deprecated**, use `styles.header` | `CSSProperties` | — | × |
| bodyStyle | ⚠️ **Deprecated**, use `styles.body` | `CSSProperties` | — | × |

> ⚠️ Semantic slots **override** the deprecated `headStyle` / `bodyStyle`
> (merge order is `{...headStyle, ...mergedStyles.header}`).

### Events

`tabChange(key: string)` and `update:activeTabKey(key: string)` are owned events. Use `@tab-change` for notification and `v-model:active-tab-key` to accept updates. JSX `onTabChange` is the same listener, called once. Controlled proposals rejected by the parent do not leak when control is released. defaultActiveTabKey only sets the initial uncontrolled value. Card owns its active/default keys, items and tabBarExtraContent over nested tabProps; other Tabs configuration, VNode labels and value-returning service functions are forwarded.

### Slots

| Name | Description |
|---|---|
| default | Card content; hidden content is not evaluated while loading |
| title / extra / cover | Current named content; slot presence overrides data, including intentional empty content |
| actions | Existing action list, with conditional items and stable VNode keys |

### Card.Meta

| Property | Description | Type | Default |
|---|---|---|---|
| avatar | Avatar | `VNodeChild` | — |
| title | Title | `VNodeChild` | — |
| description | Description | `VNodeChild` | — |
| classNames | Semantic class names (`root` / `section` / `avatar` / `title` / `description`) | `CardMetaSemanticClassNames \| ((info) => …)` | — |
| styles | Semantic styles (same five slots) | `CardMetaSemanticStyles \| ((info) => …)` | — |
| prefixCls | Class prefix (**the *card* prefix**: `x` ⇒ `x-meta`) | `string` | falls back to `apollo-card` |
| class / style | Native root attrs | `string` / `CSSProperties` | — |

> ⚠️ `avatar` sits **outside** `section`; `title` / `description` sit **inside** it.
> The root has **no** `-rtl` (`Card.Meta` does not read `direction`).

### Card.Grid

| Property | Description | Type | Default |
|---|---|---|---|
| hoverable | Hover highlight. ⚠️ **Defaults to `true`** (unlike `Card`'s `false`) | `boolean` | `true` |
| prefixCls | Class prefix (**the *card* prefix**: `x` ⇒ `x-grid`) | `string` | falls back to `apollo-card` |
| class / style | Native root attrs | `string` / `CSSProperties` | — |

### Ref

All three components expose `{ nativeElement }` (`HTMLDivElement | null`).

> ⚠️ Upstream `Card` is `forwardRef<HTMLDivElement>` (the ref *is* the DOM element), while
> `Card.Grid` / `Card.Meta` are `{ nativeElement }`. This repo normalizes all three to the
> object form (see `README.md` §2 item 1).

### Semantic DOM

| Slot | `Card` target | `Card.Meta` target |
|---|---|---|
| `root` | root `<div class="{prefixCls}">` | root `<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 | Description | Default |
|---|---|---|
| `headerBg` | Background color of the card header | `transparent` |
| `headerFontSize` | Font size of the card header | `fontSizeLG` |
| `headerFontSizeSM` | Font size of a small card header | `fontSize` |
| `headerHeight` | Height of the card header | `fontSizeLG * lineHeightLG + padding * 2` |
| `headerHeightSM` | Height of a small card header | `fontSize * lineHeight + paddingXS * 2` |
| `actionsBg` | Background color of the actions area | `colorBgContainer` |
| `actionsLiMargin` | Margin of each action item | `${paddingSM}px 0` |
| `tabsMarginBottom` | Bottom margin of the built-in tabs | `-padding - lineWidth` |
| `extraColor` | Text color of the extra area | `colorText` |
| `bodyPaddingSM` | Padding of a small card body | `12` |
| `headerPaddingSM` | Padding of a small card header | `12` |
| `bodyPadding` | Padding of the card body | `paddingLG` |
| `headerPadding` | Padding of the card header | `paddingLG` |

> ⚠️ Upstream writes `token.bodyPadding ?? token.paddingLG` for the last two, but that key
> is **not** part of antd 6's `AliasToken` (a v4 leftover) ⇒ it always resolves to
> `paddingLG`. This repo writes `paddingLG` directly (see `README.md` §2 item 2).

Runtime tuning uses CSS variables: `--apollo-card-header-height` /
`--apollo-card-body-padding` / `--apollo-card-actions-bg` … (13 of them, named the same
way as antd's `--ant-card-*`).

Current Vue contracts: Card implements default/title/extra/cover/actions slots. Slot presence wins over data, including intentional empty slots, and conditional regions preserve existing editors. The actions slot expresses the existing list; stable VNode keys preserve item identity and focus through reordering. Loading uses the real Skeleton and does not evaluate hidden body content.

Card.Meta default supplies description fallback: description slot (even empty) → explicit description data (including 0/null/false) → default. Its avatar/title/description slots stay current. Card/Grid/Meta expose their real nullable nativeElement and forward native attrs to the actual root.

All thirteen component Tokens consume current ConfigProvider theme.components.Card and alias tokens, including replacement/removal. Standalone Grid/Meta read the current theme. Semantic functions receive current resolved props. Card uses its own two surface variants and maps inherited large size to medium; Form input variant does not change Card. Native style CSS variables keep local priority. Preload static CSS for custom prefixes.


## Basic (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>
```

## Borderless (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 card (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 (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>
```

## Card in column (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 card (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 (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 card (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>
```

## With tabs (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>
```

## Support more content configuration (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>
```

## Component 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>
```

## Semantic styles (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

Provide slides through the native default slot. See the existing nine [demos](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/carousel/demo).

## API

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| effect | Transition effect | `'scrollx' \| 'fade'` | `'scrollx'` |
| dots | Show dots; object adds a dots class | `boolean \| { className?: string }` | `true` |
| dotPlacement | Dots placement; start/end imply vertical | `'top' \| 'bottom' \| 'start' \| 'end'` | `'bottom'` |
| dotPosition | Existing placement alias; use dotPlacement | `DotPlacement \| 'left' \| 'right'` | `—` |
| autoplay | Autoplay; object enables dot progress | `boolean \| { dotDuration?: boolean }` | `false` |
| autoplaySpeed | Playback interval configuration in ms | `number` | `3000` |
| speed | Transition duration in ms | `number` | `500` |
| cssEase | CSS transition easing | `string` | `'ease'` |
| infinite | Loop with cloned content instances | `boolean` | `true` |
| initialSlide | Initial index; changes reposition the carousel | `number` | `0` |
| slidesToShow | Visible slides; forced to1 in fade | `number` | `1` |
| slidesToScroll | Slides per move; forced to1 in fade | `number` | `1` |
| draggable | Mouse dragging | `boolean` | `true` |
| swipe | Allow swipe gestures | `boolean` | `true` |
| touchMove | Respond to mouse/touch movement | `boolean` | `true` |
| touchThreshold | Minimum movement divisor: viewport size/value | `number` | `5` |
| vertical | Vertical layout; inferred from placement when omitted | `boolean` | `—` |
| waitForAnimate | Reject new moves while animating | `boolean` | `false` |
| pauseOnHover | Pause while hovering content | `boolean` | `true` |
| pauseOnDotsHover | Pause while hovering dots | `boolean` | `false` |
| pauseOnFocus | Pause while focus is inside this carousel | `boolean` | `false` |
| arrows | Show native previous/next buttons | `boolean` | `false` |
| accessibility | Enable carousel keys and the list focus entry | `boolean` | `true` |
| adaptiveHeight | Adapt list height to the current slide | `boolean` | `false` |
| rtl | Horizontal RTL; defaults to current Provider direction | `boolean` | `—` |
| useCSS | Enable CSS transitions | `boolean` | `true` |
| useTransform | Use transform; false uses left/top | `boolean` | `true` |
| edgeFriction | Drag resistance at a non-looping edge | `number` | `0.35` |
| prefixCls | Root class prefix | `string` | `'apollo-carousel'` |
| id | Id on the actual root div | `string` | `—` |
| classNames | Inner semantic classes | `{ slider?: string }` | `—` |
| styles | Inner semantic styles | `{ slider?: CSSProperties }` | `—` |
| className | Existing inner class alias; prefer classNames.slider | `string` | `—` |

Native class, complete style (objects, strings or arrays), ARIA/data and listeners land on the actual root div. The former inner style prop is removed; use styles.slider for that target. The non-conflicting existing className alias remains inside. Current components.carousel presentation and Provider direction remain reactive, including removal.

The unconsumed easing API is removed directly during development. Use the working cssEase property; there is no compatibility channel.

### Slots

| Slot | Content | Scope |
| --- | --- | --- |
| default | Complete Vue slide content, including arrays, Fragments, conditional emptiness and zero | — |
| prev-arrow / next-arrow | Complete content of the existing native arrow button | `{ currentSlide: number, slideCount: number }` |

The native button owns disabled state, accessible naming, click and keyboard behavior. Migrate a former button root in an arrow slot to icon/span content. Siblings and conditional content are preserved; custom content does not duplicate the default arrow graphic.

### Events

| Event | Template | Payload |
| --- | --- | --- |
| beforeChange | `@before-change` | `(current: number, next: number)` |
| afterChange | `@after-change` | `(current: number)` |
| swipe | `@swipe` | `('left' \| 'right' \| 'up' \| 'down')` |
| edge | `@edge` | Same direction, at a non-looping edge |
| keydown | `@keydown` | Native KeyboardEvent before navigation; supports preventDefault() |

Use natural onBeforeChange/onAfterChange listeners with h(). Vue owns dispatch; attrs listeners are not called manually. There is no value model; use the public navigation methods. Each completed swipe notifies once, and a same-position request does not invent a transition.

### Reference and behavior

```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 is the actual reactive engine state, not a slick instance. Finite goTo indices wrap or clamp against current slides. Disabling animation completes immediately. Configuration/slide-structure changes settle the accepted old transition, then remeasure current settings; retired timers cannot restore stale layout. initialSlide or effective RTL changes reposition using the current initial value.

Native key handling retains keyCode support, reverses horizontal RTL arrows and supports vertical up/down. Inputs, selects, textarea, editable content, composition and canceled events do not navigate. Original interactive content retains its native Tab behavior. Inactive content is inert/aria-hidden; a visible boundary clone remains interactive. Playback retains the existing autoplaySpeed+50 schedule. Focus/content-hover/dots-hover reasons combine, and moving focus within this instance does not resume early.

Original keyed slides retain component identity. Concrete native ids and local for/ARIA references in clone trees gain stable instance suffixes. External references and component business id props remain unchanged. Parent refs belong to originals; component content slots are forwarded once at actual render time with their scope/owner, and returned clone refs are cleared.

Clones remain independent component instances and do not mirror arbitrary internal uncontrolled state. Use infinite=false for content requiring one local instance. Invisible component-internal fixed ids are not inspected or rewritten, and slots are not pre-invoked to discover hidden structure.

## Theme

The existing eight tokens remain: arrowSize, arrowOffset, dotWidth, dotHeight, dotGap, dotOffset, dotWidthActive and dotActiveWidth. Each accepts a number(px) or CSS length string and responds to current theme.components.Carousel replacement/removal. dotWidthActive is the existing alias used when dotActiveWidth is not explicit; the newer explicit value wins. CSS calc derives arrow geometry from current arrowSize, including rem lengths. Native root style can override variables explicitly.

Unsupported slick features such as responsive, rows, variableWidth, lazyLoad, asNavFor and appendDots/customPaging are not added. Existing reference/algorithm evidence remains; complete library acceptance runs later on one frozen version.


## Basic (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)

定时自动切换；`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 in (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)

`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 (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);
}
```

## Dragging (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);
}
```

## Component 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 (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);
}
```

## Dot Placement (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

Select paths from hierarchical data, with multiple selection, search and lazy loading. The floating Cascader and standalone CascaderPanel share their value and checking rules.

```ts
import { Cascader, CascaderPanel } from '@apollo-design/ui';
import type { CascaderOutputValue } from '@apollo-design/ui';
```


## Props

`ValueCell = (string | number)[]`. Single selection emits a ValueCell; multiple selection emits ValueCell[]. Clearing emits `[]` for both the value and selected options. Numeric `0`, string `'0'`, and strings containing separators remain distinct. Missing controlled paths display their original values until matching options arrive.

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| options | Hierarchical data; values are unique among siblings | BaseOptionType[] | [] |
| value / defaultValue | Current / initial uncontrolled value; a scalar represents one path segment | CascaderValue | - |
| multiple / checkable | Enable multiple selection; checkable only enables it when true | boolean | false |
| fieldNames | Reactive label/value/children field mapping | FieldNames | Standard names |
| changeOnSelect | Allow selecting intermediate nodes in single mode | boolean | false |
| showCheckedStrategy | Deduplicate displayed tags and emitted paths without changing checked descendants | SHOW_PARENT \| SHOW_CHILD | SHOW_PARENT |
| showSearch | Enable search; configure filter, sort, limit, matchInputWidth and autoClearSearchValue | boolean \| CascaderSearchConfig | false in single mode; true in multiple mode |
| searchValue / autoClearSearchValue | Search text / clear after selection; the search config takes precedence | string / boolean | '' / true |
| loadData | Load a non-leaf path without children. Pending requests deduplicate; Promise settlement clears loading and rejection reaches Vue’s error handler | (selectedOptions) => void \| Promise&lt;void&gt; | - |
| expandTrigger | Pointer expansion; keyboard also supports arrows, Enter, Escape and multiple-mode Space | 'click' \| 'hover' | 'click' |
| open / defaultOpen | Current / initial uncontrolled popup visibility | boolean | false |
| size / disabled / loading / status | Size, disabled state, loading icon and form status | SizeType / boolean / boolean / 'error' \| 'warning' | - |
| variant / bordered | outlined, borderless, filled or underlined; bordered applies when variant is omitted | SelectVariant / boolean | outlined / true |
| placeholder / notFoundContent | Static placeholder / empty content; corresponding slots take precedence, including empty slots | VNodeChild | - / 'Not Found' |
| allowClear / clearIcon / removeIcon / suffixIcon | Clear control and static icons | boolean \| { clearIcon? } / VNodeChild | true |
| expandIcon / loadingIcon | Static row icons; corresponding scoped slots take precedence | VNodeChild | Direction / loading icon |
| maxTagCount / maxTagTextLength / maxTagPlaceholder | Tag count, text length and static overflow content | number / number / VNodeChild | - |
| placement / direction | Popup placement and text direction; direction inherits the current ConfigProvider | SelectCommonPlacement / 'ltr' \| 'rtl' | bottomLeft / 'ltr' |
| popupClassName / dropdownClassName | Popup class; popupClassName takes precedence | string | - |
| popupStyle / popupMenuColumnStyle | Popup root / individual menu column ul styles | CSSProperties | - |
| popupMatchSelectWidth | Match the trigger width | boolean \| number | false |
| getPopupContainer | Popup container, inherited from the current ConfigProvider when omitted | (node) => HTMLElement | - |
| classNames / styles | Semantic objects or `({ props }) => object` | CascaderSemanticClassNames / CascaderSemanticStyles | - |
| id / prefixCls | Input ID / component prefix | string | Generated / apollo-cascader |

Native class/style/attrs reach the actual trigger. aria-label and aria-labelledby reach the input. Semantic targets are root, prefix, suffix, input, placeholder, content, item, itemContent, itemRemove, clear, and popup.root/list/listItem. Provider, semantic root styles and native root styles merge in that order.

## Slots

Slots preserve complete Vue content, including text, zero, multiple nodes and conditional presence.

| Slot | Scope | Purpose |
| --- | --- | --- |
| default | - | Complete custom trigger content |
| displayRender | { labels, selectedOptions } | Selected path content; defaults to slash-separated paths in single mode and the last segment in multiple mode |
| optionRender | { option, pathOptions } | Ordinary option content |
| searchRender | { inputValue, pathOptions, fieldNames } | Search result content |
| popupRender | { menu: VNode } | Wrap the bound menu using `<component :is="menu" />`, preserving its state and events |
| expandIcon / loadingIcon | { option } | Per-option icons |
| suffixIcon / searchIcon | { focused, open, searchValue, showSearch, loading } | Suffix / focused search icon |
| maxTagPlaceholder | { omittedValues: { value: ValueCell, label, disabled? }[] } | Overflow tag content |
| placeholder / notFoundContent / clearIcon / removeIcon | - | Corresponding content |

## Emits and models

| Event | Payload |
| --- | --- |
| update:value | value: CascaderOutputValue |
| change | value: CascaderOutputValue, selectedOptions: CascaderSelectedOptions |
| update:open / openChange | open: boolean |
| update:searchValue / search | text: string |
| focus / blur | FocusEvent |
| clear | None |
| popupScroll | Event |
| keydown / keyup / mousedown | Corresponding native event |

Use v-model:value, v-model:open and v-model:searchValue. Controlled updates remain proposals until accepted by the parent. Releasing control with undefined retains the last received value. Vue Emits deliver owned notifications exactly once, including listener arrays.

## Ref and Panel

The selector ref exposes `nativeElement: HTMLElement | null`, `focus(options?: FocusOptions)` and `blur()`.

CascaderPanel / Cascader.Panel contains only menu columns. It supports options, value/defaultValue, multiple, fieldNames, changeOnSelect, showCheckedStrategy, loadData, expandTrigger, expandIcon, loadingIcon, direction, disabled, notFoundContent, popupMenuColumnStyle and classNames/styles. It emits update:value/change and accepts optionRender/searchRender/expandIcon/loadingIcon/notFoundContent slots. Native attrs reach its focusable root; keyboard navigation uses the same OptionList.

Cascader.SHOW_PARENT and Cascader.SHOW_CHILD expose the strategy constants. The internal alias `_InternalPanelDoNotUseOrYouWillBeFired` still points to Panel (historical D113).

## Development migration and theme

Function props displayRender, optionRender and popupRender become their named scoped slots. showSearch.render becomes #searchRender; nested searchValue/onSearch become the top-level model and @search. Function maxTagPlaceholder and icon functions become slots. Inactive trigger/placeholder2 and duplicate popupVisibleChange/dropdownVisibleChange notifications are removed.

All eight Cascader tokens update on the trigger, teleported popup and Panel: controlWidth(184), controlItemWidth(111), dropdownHeight(180), optionSelectedBg, optionSelectedFontWeight, optionPadding, menuPadding and optionSelectedColor. Select-specific component overrides do not change Cascader ownership.


## Basic (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)

`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 (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 (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 (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 (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)

`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 (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)

`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 (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)

多选下用 `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`，观察浮层在触发器上方/下方、左侧/右侧对齐的差异。

### 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)

`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)

`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>
```

## Component 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 (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 (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 (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 (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 (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)

`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 (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 (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


Select one or more from a set of options.

## When To Use

- Used to select multiple options from a set.
- A single checkbox alone expresses two states (use `indeterminate` for half-checked).

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/checkbox/demo) (8, covering the main antd scenarios.

Current native contract (2026-10-30): `change(event: Event, checked: boolean)` emits the actual event and requested checked snapshot; `update:checked` emits a boolean. Group change/update:value emit scalar value arrays. Rejected controlled proposals restore actual checked/indeterminate DOM properties and never become accepted values on release. DOM handles are nullable. Current Provider semantics, native style strings/arrays, dynamic skipGroup registration and native form values are supported. The old target/nativeEvent wrapper is removed.

## API

### Checkbox

| Prop | Description | Type | Default |
|---|---|---|---|
| checked | Controlled checked state | `boolean` | — |
| defaultChecked | Initial checked state | `boolean` | `false` |
| indeterminate | Indeterminate state (affects style and `input.indeterminate`) | `boolean` | `false` |
| disabled | Disabled (`props ?? group.disabled ?? DisabledContext`) | `boolean` | — |
| value | ⚠️ Not a valid prop outside a Group (usage warning); option value inside | `string \| number \| boolean` | — |
| skipGroup | Detach from Group management | `boolean` | `false` |
| name / id / tabIndex / required / autoFocus / title | Native attributes | — | — |
| @change | Native event and requested checked snapshot | `(event: Event, checked: boolean)` | — |
| @click / @mouseenter / @mouseleave / @focus / @blur / @keydown / @keypress | Passthrough (onClick is bubble-locked) | — | — |
| classNames / styles | Semantic slots `{ root, icon, label }` (object or function) | — | — |

### Checkbox.Group

| Prop | Description | Type | Default |
|---|---|---|---|
| options | Options (string/number ⇒ `{label, value}`; nullish values filtered) | `(string \| number \| CheckboxOptionType)[]` | `[]` |
| value / defaultValue | Controlled / uncontrolled selected values | `T[]` | `[]` |
| onChange | Callback (sorted by options/registration order, removed values filtered) | `(checkedValue: T[]) => void` | — |
| disabled | Disable the whole group (option-level `disabled` wins) | `boolean` | — |
| name | `name` of all inputs (also lands on the root div) | `string` | — |
| role | Root role | `string` | `'group'` |
| class / style | Root attributes | — | — |

### Slots

| Name | Description |
|---|---|
| default | Checkbox text (isRenderable: `0` renders, `false`/`''` don't) |
| Group default | Custom child Checkboxes (mutually exclusive with options) |

## Ref

| Name | Type |
|---|---|
| nativeElement | `HTMLElement \| null` |
| input | `HTMLInputElement \| null` |
| focus / blur | `(options?: FocusOptions) => void` / `() => void` |

Group's ref is `HTMLDivElement`.

## Theme (Component Token)

None — Checkbox has no Component Token (same as antd); styles consume alias tokens
(size = `controlInteractiveSize`). Use semantic `classNames` / `styles` instead.


## Basic (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 (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>
```

## Controlled (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 (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 (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 (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>
```

## Semantic styles (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 (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


Group content behind native disclosure buttons. Both `items` and declared `CollapsePanel` children use the same real Vue component. See all nine [demos](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/collapse/demo).

## API

### Collapse

| Prop | Description | Type | Default |
|---|---|---|---|
| items | Data panels; a present array, including [], takes priority over the default slot | `CollapseItemType[]` | — |
| activeKey / defaultActiveKey | Controlled keys / initial uncontrolled keys; normalized to strings | `string \| number \| (string \| number)[]` | — |
| accordion | Only one open disclosure | `boolean` | `false` |
| bordered / ghost | Border / transparent appearance | `boolean` | `true` / `false` |
| size | Local size, otherwise current Provider componentSize | `'small' \| 'middle' \| 'large'` | `middle` |
| collapsible | Default: header whitespace and title button; header: title button; icon: icon button; disabled: no activation | `'header' \| 'icon' \| 'disabled'` | — |
| headingLevel | Heading level; nested Collapse increments up to 6 | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` |
| expandIconPlacement | Logical icon position; extra remains an independent region | `'start' \| 'end'` | `start` |
| destroyOnHidden | Destroy body after completed close; forceRender takes priority | `boolean` | `false` |
| prefixCls | Full component prefix; preload matching static CSS | `string` | Provider prefix + `-collapse` |
| classNames / styles | root, header, title, body and icon semantic regions | `CollapseSemanticClassNames / CollapseSemanticStyles` | — |

Legacy destroyInactivePanel / expandIconPosition still work and warn in development; current props take priority. Native class, style, ARIA, data, role and DOM listeners reach the root. Native style wins conflicting Provider and semantic root styles.

| Slot | Content / scope |
|---|---|
| default | Declared CollapsePanel children; not read when items is an array |
| expandIcon | `{ key, isActive, prefixCls, collapsible, direction }`; slot presence wins, including empty output, zero and Fragments |

The top-level expandIcon renderer prop has migrated directly to `#expandIcon`. Programmatic defaults remain available through `ConfigProvider components.collapse.expandIcon`; a local slot wins.

| Event | Payload |
|---|---|
| update:activeKey | `string[]`; supports `v-model:active-key` |
| change | `string[]`, once per allowed activation |

Controlled requests do not change presentation until accepted. Releasing control uses the last accepted value. Later defaultActiveKey changes do not reset state. A ref exposes `nativeElement: HTMLDivElement | null`.

### Items and CollapsePanel

| Field | Item data | Declared Panel |
|---|---|---|
| key | string / number; defaults to array index | Vue key; otherwise numbered by initial mount order. Use stable explicit keys for dynamic Panels |
| label / header | VNode data; label wins | header is text; label is a VNode fallback |
| children / extra | VNode data, including zero and Fragments | default / #extra slots |
| showArrow / forceRender | boolean, defaults true / false | Same |
| collapsible / destroyOnHidden | Override owning Collapse | Same |
| onItemClick / @item-click | Normalized string key, once per activation | Vue event; supports .once |
| className / style | Item root class / native StyleValue | Same; also supports native class, attrs and listeners |
| classNames / styles | Five regions; item overrides global, root targets this item | Same |
| headerClass / id | Header class / item root ID | Same |
| prefixCls | — | Full Panel prefix; inherits owning Collapse tokens; preload matching CSS |
| disabled | — | Legacy disabled input with a warning; explicit collapsible wins |

A present Panel `#header` overrides header and label, including empty output. Removing a conditional slot restores the fallback. Titles belong to a native heading/button: use phrasing content such as text and spans. Put independent buttons and inputs in `#extra`, outside that heading/button; stopping propagation is unnecessary. The default slot holds body content. Panel lifecycle hooks run normally.

## Keyboard, state and motion

Tab reaches disclosure buttons; Enter and Space activate them. Disabled buttons cannot activate. icon with showArrow=false is explicitly disabled and warns in development. Empty custom icon output still retains a named button. An empty title receives a default accessible name; applications should supply meaningful titles.

Body content mounts lazily and stays mounted after closing by default, preserving input state and selection. Closed content is hidden / inert. destroyOnHidden removes body content after closing while keeping the stable region/aria-controls relationship. forceRender always renders and retains the body, even with destroyOnHidden. Closing an editor that owns focus returns focus to its trigger; outside focus stays outside. Motion follows the current theme, reduced-motion preference and prefix.

When an external update closes an editor whose trigger is disabled, focus moves to its owning Collapse root. A temporary tabindex=-1 remains only while that root owns focus; native attrs resume on blur.

## Theme

Current `theme.components.Collapse` supports ten CSS string tokens: headerPadding, headerPaddingSM, headerPaddingLG, headerBg, contentPadding, contentPaddingSM, contentPaddingLG, contentBg, borderlessContentPadding and borderlessContentBg. They map to `--<component-prefix>-header-padding` and related variables. Ghost backgrounds remain transparent.

Default padding and derived panel radius follow current Alias values. Default body horizontal padding keeps the 16px design constant. borderlessContentBg defaults to transparent. An explicit empty ThemeProvider resets defaults; CSS-only scopes retain inherited variables. See the [development migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/collapse-contracts.md).


## Basic (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)

`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 & Ghost (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 & Collapsible (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)

通过 `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 Header and Extra (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` 移除折叠面板的背景与边框，开关可实时对比幽灵模式与默认样式。

### 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)

通过 `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>
```

## Component 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


A color selection component: clicking the trigger opens a picking panel that supports
single colors / gradients, preset palettes and multiple encoding formats.

## When To Use

- When the user needs to pick a color (or a gradient);
- When a preset palette lets the user pick a color quickly;
- When a color value must be maintained in a **controlled** way inside a form.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/color-picker/demo) (**16** demos, mirroring antd's user-visible demos).

| demo | Description |
|---|---|
| `base` | The simplest usage (`defaultValue` + trigger) |
| `size` | Trigger sizes `small` / default / `large` (with `showText`) |
| `controlled` | Two controlled rhythms: `value` + `@change` / `@changeComplete` |
| `line-gradient` | `mode` single / gradient (can be an array) |
| `text-render` | Default text and the #showText scoped slot |
| `disabled` | Disabled state |
| `disabled-alpha` | `disabledAlpha` removes transparency |
| `allowClear` | Clear entry and the "cleared" state |
| `trigger` | Custom trigger via the default slot |
| `trigger-event` | `trigger="hover"` |
| `format` | `format` as `hex` / `hsb` / `rgb` |
| `presets` | Grouped preset colors |
| `presets-line-gradient` | Gradient preset colors |
| `panel-render` | `panelRender` takes over the panel |
| `style-class` | `classNames` / `styles` as objects or functions |
| `pure-panel` | Static panel via `ColorPickerPurePanel` |

⚠️ The upstream `_semantic` demo (the "semantic DOM" illustration, `simplify`-only) is
**not ported**; semantic-slot coverage is handled by `semantic.test.ts`.

## API

Native class, id, ARIA and mouse listeners target the trigger. Known Vue event keys such as `@mousedown` retain their Once/Passive/Capture suffixes. Attr-only updates read current values and listener replacement does not duplicate calls.

### Props

| Property | Description | Type | Default | Global config |
|---|---|---|---|---|
| mode | Mode: single / gradient (an array enables both) | `'single' \| 'gradient' \| ModeType[]` | `'single'` | × |
| value | Controlled value (use with `v-model:value`) | `ColorValueType` | — | × |
| defaultValue | Uncontrolled initial value. **Omitting both ⇒ the "cleared" state** | `ColorValueType` | — | × |
| format | Current encoding format (use with `v-model:format`) | `'hex' \| 'rgb' \| 'hsb'` | `'hex'` | × |
| defaultFormat | Uncontrolled initial format | `'hex' \| 'rgb' \| 'hsb'` | — | × |
| disabledFormat | Disable the format dropdown (the dropdown is gone, the input remains) | `boolean` | `false` | × |
| open | Controlled open state (use with `v-model:open`) | `boolean` | — | × |
| trigger | Trigger mode | `'click' \| 'hover'` | `'click'` | × |
| placement | Popup placement | `TriggerPlacement` | `'bottomLeft'` | × |
| arrow | Whether to show the arrow | `boolean \| { pointAtCenter?: boolean }` | from ConfigProvider | ✅ |
| getPopupContainer | Container to mount the popup into | `(triggerNode: HTMLElement) => HTMLElement` | — | × |
| autoAdjustOverflow | Auto-adjust on overflow | `boolean` | `true` | × |
| destroyTooltipOnHide | ⚠️ **Deprecated**, use `destroyOnHidden` | `boolean \| { keepParent?: boolean }` | `false` | × |
| destroyOnHidden | Unmount the popup after closing | `boolean` | `false` | × |
| allowClear | Whether clearing is allowed | `boolean` | `false` | × |
| disabledAlpha | Disable alpha (the panel drops the alpha slider and input; a semi-transparent color is forced opaque) | `boolean` | `false` | × |
| presets | Preset panel (only an **array** renders it, plus an extra `Divider`) | `PresetsItem[]` | — | × |
| showText | Show default text; customize it with #showText | `boolean` | `false` | × |
| size | Size | `'small' \| 'middle' \| 'large' \| string` | from ConfigProvider | ✅ |
| disabled | Disabled | `boolean` | from ConfigProvider | ✅ |

| classNames | Semantic class names (`root` / `body` / `content` / `description` / `popup`); function form supported | `ColorPickerSemanticClassNames \| ((info) => …)` | — | ✅ |
| styles | Semantic styles (6 slots — one more than `classNames`: `popupOverlayInner`); function form supported | `ColorPickerSemanticStyles \| ((info) => …)` | — | ✅ |
| prefixCls | Class name prefix | `string` | from ConfigProvider, fallback `apollo-color-picker` | × |
| class / style | Native attrs target the actual trigger; use popup.root for the popup | Vue class / StyleValue | — | × |

#### ColorValueType

```ts
type SingleValueType = AggregationColor | string;
type LineGradientType = { color: SingleValueType; percent: number }[];
type ColorValueType = SingleValueType | null | LineGradientType;
```

⚠️ **"Cleared" is not `null`** — it is a color instance with alpha=0 and
`cleared = true`. The trigger switches between `ColorClear` (transparent checkerboard)
and `ColorBlock` (a color swatch) based on it.

Color instance numeric inputs are unsigned 24-bit RGB integers. Object channels accept finite numbers and numeric strings; HSB s/b use 0–1. Invalid numeric inputs throw instead of becoming a default color.

#### PresetsItem

| Property | Description | Type | Default |
|---|---|---|---|
| label | Group title | `VNodeChild` | — |
| colors | Colors of this group (strings / color instances / **gradients**) | `(string \| AggregationColor \| LineGradientType)[]` | — |
| defaultOpen | Whether the group is expanded initially | `boolean` | `true` |
| key | Group key (falls back to the index) | `string \| number` | — |

### Events

| Event | Description | Parameters |
|---|---|---|
| update:value | The update channel of `v-model:value` (**emitted together with** `change`) | `(value: Color)` |
| change | Value change. ⚠️ The second argument is the CSS string from `toCssString()` | `(value: Color, css: string)` |
| changeComplete | Value change **complete**. ⚠️ **Not emitted while dragging** | `(value: Color)` |
| clear | Clear | — |
| update:open | The update channel of `v-model:open` (**emitted together with** `openChange`) | `(open: boolean)` |
| openChange | Open state change | `(open: boolean)` |
| update:format | The update channel of `v-model:format` (**emitted together with** `formatChange`) | `(format?: ColorFormatType)` |
| formatChange | Format change. ⚠️ **Not emitted for an identical value** | `(format?: ColorFormatType)` |

### Slots

| Slot | Description | Parameters |
|---|---|---|
| default | Trigger content (equivalent to upstream `children`). Providing it **completely replaces** the built-in trigger | — |
| panelRender | Custom panel; panel is a stable Vue component reference | `{ panel: Component; extra: ColorPickerPanelRenderExtra }` |
| showText | Complete trigger text from the current slot | `{ color: Color }` |

`extra.components` provides two component references `{ Picker, Presets }` so a custom
panel can lay them out freely:

```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

This round adds no methods or Expose API.

### Design Token

**Component Tokens users can override: 0** (same as antd).

This port declares upstream's 9 `mergeToken` derived values as
`--apollo-color-picker-*` (**not user-overridable**; an intentional difference, see
`README.md` §2 / §4):

| Variable | Value |
|---|---|
| `--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))` |

### Semantic DOM

| Slot | Lands on |
|---|---|
| `root` | The native trigger button, or the custom trigger host |
| `body` | The swatch / transparent checkerboard inside the trigger |
| `content` | The **inner** layer of the swatch (`ColorBlock`'s inner) |
| `description` | The text container next to the trigger |
| `popup.root` | The popup root (**nested slot**) |
| `popupOverlayInner` | ⚠️ **`styles` only**, mapped to Popover's `styles.container` |

⚠️ `classNames` has 5 slots while `styles` has 6 — **intentionally asymmetric**
(matching upstream).

## FAQ

### Why is the trigger a transparent checkerboard when `defaultValue` is omitted?

Because upstream's default value is literally "cleared": `useModeColor` receives
`undefined`, so `AggregationColor` takes the `cleared` branch (alpha=0). Pass an explicit
`defaultValue` to see a color.

### Why does `disabledAlpha` rewrite a semi-transparent color?

Upstream behavior: under `disabledAlpha`, if the current color has `alpha < 100`, the
value received by `change` / `changeComplete` is rewritten to opaque by `genAlphaColor`
(and a dev-time warning is emitted).

### Development migration

- Replace the panelRender function prop with #panelRender. Its panel value is now a stable Vue component reference, rendered with <component :is="panel" />.
- showText accepts boolean. Use #showText for custom content; its scope contains the current color, including conditional and empty slots.
- Default triggers, preset choices and clear actions use native buttons. The cleared trigger graphic is decorative. The original reference remains intact; semantic tests derive only these reviewed differences.
- size uses the shared SizeType. Native class/style target the trigger; customize popup.root and popupOverlayInner for popup targets.
- Rejected controlled open/format requests do not leak into uncontrolled state. disabledAlpha normalizes each incoming gradient stop while preserving the cleared action.
- PurePanel presents the actual panel in normal flow, forwarding native host attrs, its panelRender slot and Vue events without size polling.


## Basic (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>
```

## Trigger Size (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 (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 (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>
```

## Render Trigger Text (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` 禁用整个组件；触发器仍会渲染当前颜色。

### 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 (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>
```

## Clear Color (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>
```

## Custom Trigger (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>
```

## Custom Trigger Event (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>
```

## Color Format (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` 传入分组预设色，面板底部会出现对应色块列表。

### 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-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>
```

## Custom Panel (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 (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 Panel (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


Provide current theme, language, size, disabled state, direction and component defaults to an application or feature subtree.

## Demos

Eight paired examples cover prefixes, language, component defaults, size/disabled, themes, dynamic size, direction and `useConfig`.

## API

### Props

| Prop | Description | Type | Default |
|---|---|---|---|
| scopeTag | Optional native scope host. Omit to remain renderless; choose a tag valid in its HTML / SVG context | `ConfigProviderScopeTag` | — |
| prefixCls | Component DOM class prefix; custom prefixes require matching static CSS | `string` | `'apollo'` |
| iconPrefixCls | Independent icon class prefix | `string` | `'apollo-icon'` |
| getPopupContainer | Current floating-content container resolver | `(trigger?: HTMLElement) => HTMLElement \| ShadowRoot` | — |
| getTargetContainer | Scroll-target resolver for consumers such as Affix / Anchor | `() => HTMLElement \| Window` | — |
| renderEmpty | Empty-content factory; null, undefined, false and empty strings intentionally render nothing | `RenderEmptyHandler`, returning `VNodeChild` | Consumer default |
| locale | Current language data; replacement, deep edits and withdrawal preserve business content | `Locale` | Inherited; missing fragments fall back to English |
| componentSize | Control size default; explicit component props win | `'small' \| 'medium' \| 'middle' \| 'large'` | Inherited |
| componentDisabled | Disabled default; explicit false overrides inherited true | `boolean` | `false` |
| direction | Layout direction | `'ltr' \| 'rtl'` | Inherited |
| virtual | Default virtualization flag for supporting consumers | `boolean` | `true` |
| variant | Default appearance for input, selection and form controls | `'outlined' \| 'borderless' \| 'filled' \| 'underlined'` | Inherited |
| popupMatchSelectWidth | Popup-width default for Select / TreeSelect / Cascader; local props win | `boolean` | Consumer default |
| theme | Preset, appearance, user/component tokens, algorithm(s) and CSS-variable prefix | `ConfigProviderThemeConfig` | Inherited |
| warning | Development warning behavior; strict=false aggregates deprecated usage | `{ strict?: boolean }` | `{}` |
| components | Defaults supported by each component contract, keyed by its consumer name; arbitrary props are not applied automatically | `Record<string, ComponentConfigLike>` | — |
| divider | Precise Divider configuration alias | `DividerConfig` | — |
| empty | Precise Empty configuration alias | `EmptyConfig` | — |
| spin | Precise Spin configuration alias | `SpinConfig` | — |
| form | Consumed Form defaults: validation messages, required marks, colon, labels and semantic styles | `FormConfig` | — |

### Inheritance and content

Undefined local values inherit, including after withdrawing a previous override. Component names merge across providers; the same component configuration is replaced as a whole. Precise aliases override the corresponding map entry, and explicit component props take precedence.

Theme tokens merge by key; component tokens merge by component name and token key. inherit=false resets inherited tokens and component tokens while retaining the CSS-variable prefix. Validation messages combine defaults, the parent FormProvider, local language and effective form configuration. Map and direct form aliases share the same channel.

`theme.preset` accepts a public `ThemePreset` object. Built-ins have separate `@apollo-design/theme/presets/default`, `mono`, and `material3` imports. Appearance (`mode: light|dark|system`) is independent of the preset. Preset and appearance seeds are merged before user seeds enter derivation; user Alias and component tokens retain final precedence. A local explicit algorithm keeps its complete original chain and replaces inherited mode; local mode replaces an inherited algorithm. ConfigProvider inherits raw configuration by default. The foundation ThemeProvider keeps its existing empty-theme reset and only inherits with `inherit:true`. Live providers observe system appearance after mounting and release subscriptions; server system rendering defaults to light. The active provider projects complete variables, so Mono does not require the default `tokens.css`; UI structural styles are still required.

The default slot accepts complete Vue content, multiple roots and conditional children. There are no business emits, model or exposed methods. Without scopeTag, provider attrs are ignored. With an explicit scopeTag, attrs land on that native host and native styles win. Choosing another host tag follows Vue's structural root-replacement behavior; theme and language updates preserve the logical content tree.

### Theme, SSR and styles

The default provider stays renderless. Client-side variable projection follows actual native roots, dynamic roots and Portal content. It preserves business nodes, respects native CSS-variable declarations and releases its own writes on withdrawal or unmount.

SSR serializes Alias variables on direct native slot roots. An opaque component that does not forward attrs, or plain text, cannot receive an automatic server-side scope. For a complete first paint, provide a valid native host, such as `<ConfigProvider scope-tag="section" :theme="theme">`. A table can use `<table><ConfigProvider scope-tag="tbody"><tr>…</tr></ConfigProvider></table>`. The default renderless provider also works inside existing tbody, ul, select and SVG contexts. Hydrate with matching configuration and content.

Published CSS includes the apollo prefix. The prefix demo imports separate build-time brand CSS. Custom CSS-variable prefixes likewise require matching consumer styles. Component tokens take effect where the component consumes them. Theme updates change variables; they do not generate selectors at runtime.

### Deprecated aliases

| Old | Replacement |
|---|---|
| autoInsertSpaceInButton | components.button.autoInsertSpace |
| dropdownMatchSelectWidth | popupMatchSelectWidth |

### Static API and composables

| API | Behavior |
|---|---|
| ConfigProvider.ConfigContext | An InjectionKey; prefer useConfigContext() for its default value |
| ConfigProvider.config / setGlobalConfig | Module-level setter accepting prefixCls, iconPrefixCls and theme; returns void. Static consumers such as Modal read their supported values; use provider props for reactive application state |
| ConfigProvider.useConfig / useConfig | Returns componentDisabled and componentSize ComputedRefs |
| useDirection / useThemeConfig | Current computed direction / theme; absent inactive theme sources yield undefined |
| useComponentConfig(name) | Lazy current configuration view; read in render/computed rather than destructuring primitive values during setup |

Locale useLocale(name) returns `[ComputedRef<fragment>, ComputedRef<code>]`; read `.value` in script. Theme useTheme().config is a writable instance ref: assignment replaces the effective configuration, deep edits do not mutate props or parents, and external source changes restore external authority.

The current development version removes unused csp, wave, popupOverflow, theme.prefixCls and the useLocaleReactive duplicate API. See the [grouped migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/config-provider-contracts.md).

The nearest explicit `ThemeProvider` is a current theme source, including an empty `{}` reset to defaults. Nested `ConfigProvider` instances project that source onto their native roots. With no explicit source, existing CSS-variable inheritance remains intact.


## prefixCls (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)

`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 (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>
```

## componentSize / componentDisabled (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)

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)

通过 `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 (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>
```

## useConfig (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


> Current API (2026-10-30): use named scoped slots for dynamic content (`cellRender`, `panelRender`, `extraFooter`, `tagRender`) and named decoration/preset slots. Legacy render props, `addon`, notification props and unimplemented PurePanel types are removed. Use owned emits, including `@select`; `@keydown` receives one native KeyboardEvent and honors preventDefault(). `v-model:mode` is supported. ArrowDown enters a readonly picker panel; arrows navigate, Enter/Space selects, Escape restores input focus. DOM refs are nullable.

# DatePicker

To select or input a date.

At viewport widths of 575px or less, date-time content and range panels wrap within the viewport. All date cells, time columns and confirmation controls remain available, including native keyboard selection of both range endpoints. Wider viewports retain the side-by-side layout.

## When To Use

- When the user needs to input a date, they can click the standard input box and pick
  from the popped-up date panel;
- Use `picker` to switch between granularities (`date` / `week` / `month` / `quarter` /
  `year` / `time`);
- Use `RangePicker` to select a date range.

## Import

```ts
import { DatePicker, RangePicker } from '@apollo-design/ui';
```

## Examples



<!-- Examples are collected automatically from `demo/*.md` (title / order / description)
     and `demo/*.vue`. Covered: basic, range, disabled date, min/max, date & time,
     12-hour clock and steps, presets, controlled, format, size/status/variant,
     multiple, cell render, need confirm, extra footer, range with time, panel render,
     placement, allow empty. -->

## API

### DatePicker

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| value (`v-model:value`) | Controlled value. `null` means "controlled and empty" | `DateType \| DateType[] \| null` | —— |
| defaultValue | Uncontrolled initial value | same as above | —— |
| picker | Granularity | `'time' \| 'date' \| 'week' \| 'month' \| 'quarter' \| 'year'` | `'date'` |
| mode | Current panel view granularity (handle `panelChange` yourself when controlled) | `'time' \| 'date' \| 'week' \| 'month' \| 'quarter' \| 'year' \| 'decade'` | —— |
| format | Format: string / array / mask object / **function** | `DatePickerFormat` | derived from `picker` + locale |
| showTime | Show time selection (`true` or a config object) | `boolean \| SharedTimeProps` | —— |
| showWeek | Show week number (week picker only) | `boolean` | —— |
| showToday | Show "Today" | `boolean` | `true` |
| showNow | Show "Now" in the time panel | `boolean` | `true` |
| open (`v-model:open`) | Controlled open state. `undefined` = uncontrolled | `boolean` | —— |
| defaultOpen | Uncontrolled initial open state | `boolean` | `false` |
| needConfirm | Whether an "OK" click is required. ⚠️ **Default depends on granularity**: `true` for `time` / `datetime`, `false` otherwise | `boolean` | see left |
| multiple | Multiple selection | `boolean` | `false` |
| order | Sort by date when `multiple` | `boolean` | `true` |
| presets | Shortcut options. `value` accepts a **function** (lazy) | `ValueDate[]` | —— |
| disabledDate | Disabled dates | `(date, info) => boolean` | —— |
| minDate / maxDate | Selectable bounds (a plain date, as upstream) | `DatePickerDate` | —— |
| placeholder | Placeholder | `string` | from locale |
| locale | Locale (deep-merged with `ConfigProvider`'s `locale.DatePicker`) | `PickerLocale` | —— |
| size | Size (falls back to `ConfigProvider`) | `'small' \| 'medium' \| 'middle' \| 'large'` | —— |
| variant | Variant | `'outlined' \| 'borderless' \| 'filled' \| 'underlined'` | `'outlined'` |
| status | Validation status. ⚠️ **Class name only — does not change `aria-invalid`** | `'error' \| 'warning'` | —— |
| disabled | Disabled | `boolean` | `false` |
| inputReadOnly | Read-only input (panel only, no typing) | `boolean` | `false` |
| allowClear | Allow clearing. Pass an object to customize the icon | `boolean \| { clearIcon }` | `true` |
| suffixIcon | Suffix icon | `VNodeChild` | calendar icon |
| prefix | Prefix | `VNodeChild` | —— |
| clearIcon | **deprecated** → `allowClear.clearIcon` | `VNodeChild` | —— |
| popupClassName | **deprecated** → `classNames.popup` | `string` | —— |
| popupStyle | **deprecated** → `styles.popup` | `CSSProperties` | —— |
| dropdownClassName | Same as `popupClassName` (**deprecated**) | `string` | —— |
| placement | Popup placement. Defaults by direction (LTR `bottomLeft` / RTL `bottomRight`) | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'` | —— |
| popupAlign | Popup align offset | `AlignType` | —— |
| builtinPlacements | Custom placement table | `Record<string, AlignType>` | 4 built-in |
| getPopupContainer | Popup mount container | `(node) => HTMLElement` | `document.body` |
| transitionName | Popup motion name | `string` | `${rootPrefixCls}-slide-up` |
| required | Native `required` (forwarded to `input[required]` and `aria-required`) | `boolean` | —— |
| name / autoComplete / id | Bound to the native `input`; pair `id` with `label for` | `string` | `autoComplete: 'off'` |
| tabIndex / tabindex | Native input Tab order; `tabindex` is also accepted as a Vue attr | `number` | —— |
| autoFocus | Focus the first enabled input on mount | `boolean` | `false` |
| prefixCls | Class prefix. ⚠️ Defaults to **`apollo-picker`** (not `apollo-date-picker`) | `string` | —— |
| class / style | **Native root attrs** (replacing upstream `className` / `rootClassName` / `style`) | `string \| array \| object` / `CSSProperties` | —— |
| classNames / styles | Semantic class names / styles (**4 flat + 7 nested `popup`**). `popup` accepts a **string** (= `popup.root`). `classNames.root` / `styles.root` land on the **selector root** (merged with native `class` / `style`; native wins) | `DatePickerSemanticAllType` | —— |

### Top-level time config

Upstream `PickerProps extends Omit<SharedTimeProps, 'format' | 'defaultValue'>`
(`SinglePicker.d.ts`) ⇒ these are **top-level props** (no need to nest them in `showTime`);
they are merged with `showTime` inside `getTimeProps` (same-named keys in `showTime` **win**).
They apply to both the date and the time panel.

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| use12Hours | 12-hour clock (adds an AM/PM column) | `boolean` | —— |
| showHour / showMinute / showSecond / showMillisecond | Explicitly toggle a column | `boolean` | derived from the format |
| hourStep / minuteStep / secondStep / millisecondStep | Step inside a column | `number` | `1` / `1` / `1` / `100` |
| hideDisabledOptions | Skip disabled options instead of rendering them disabled | `boolean` | `false` |
| disabledTime | Per-day disabled options (the three legacy `disabledHours`-style keys are noted in the compatibility doc) | `(date) => DisabledTimes` | —— |
| changeOnScroll | Commit the value as soon as the column scrolls | `boolean` | `false` |
| defaultOpenValue | **Anchor for the panel when empty** (does not write a value; confirming does) | `DatePickerDate` | —— |

### Events

| Event | Description | Payload |
| --- | --- | --- |
| `update:value` | `v-model:value` channel | `(date)` |
| `change` | Value changed (emitted **together with** `update:value`) | `(date, dateString)` |
| `calendarChange` | Every change while picking (even before submit) | `(date, dateString, info)` |
| `ok` | "OK" clicked | `(date)` |
| `openChange` | Popup open/close | `(open, config?)` |
| `update:open` | `v-model:open` channel | `(open)` |
| `pickerValueChange` | Panel view value changed | `(date, info)`, `info.source` is `'reset' \| 'panel'` |
| `update:pickerValue` | `v-model:pickerValue` channel | `(date)` |
| `panelChange` | Panel granularity changed | `(value, mode)` |
| `clear` | Clear button clicked | —— |
| `focus` / `blur` | Focus in/out | `(event, info)` |
| `invalid` | Invalid typed value | `(invalid)` |
| `submit` | Form submit | `(event)` |
| `keydown` | Keydown (channel of the deprecated `onKeyDown`) | `(event: KeyboardEvent)` |

### Slots

| Slot | Description | Params |
| --- | --- | --- |
| `panelRender` | Wraps the original panel | `{ originPanel }` |
| `extraFooter` | Extra footer content | `{ mode }` |
| `cellRender` | Cell content | `{ current, info }` |

### Expose

| Method | Description | Type |
| --- | --- | --- |
| `focus` | Focus the input | `(options?: FocusOptions) => void` |
| `blur` | Blur | `() => void` |
| `nativeElement` | Root node | `HTMLDivElement` |

### RangePicker (differences from DatePicker)

| Property | Difference |
| --- | --- |
| `value` / `defaultValue` | Tuple `[start, end]`. ⚠️ **`null` and `undefined` mean different things**: `null` = "clear this end", `undefined` = "not picked yet" |
| `placeholder` | Tuple `[string, string]` |
| `id` | `string \| { start?: string; end?: string }`; a string identifies only the start input; an object identifies each endpoint, without generated ids |
| `separator` | Separator between the two ends. **The default one carries `aria-hidden`; a custom one drops it** |
| `allowEmpty` | Allow one end to be empty (`boolean` or a tuple) |
| `disabled` | `boolean` or a tuple. ⚠️ The `-disabled` root class is added only when **both ends** are disabled |
| `showTime` | `boolean \| RangeTimeProps` (`disabledTime` gets two extra params) |
| `presets` | `RangeValueDate[]` |
| `onSelect` | **deprecated**, and only effective when `picker === 'time'` |
| `focus` | Different signature: `(index?) => void` |
| `startInput` / `endInput` | The two native inputs |

### Native attribute targets

`class`, `style`, `data-*` and native mouse listeners target the selector root. `id`, `tabIndex` / `tabindex`, `name`, `required`, `autoComplete`, `autoFocus` and `aria-*` target the actual inputs. Shared range attributes apply to both endpoints. Input validation controls `aria-invalid`; `aria-required` follows `required` unless explicitly supplied. The component owns the controlled value, input handlers and refs.

F01 moves input ARIA and Tab order from the root to the input. Update DOM queries for these attributes accordingly. Use object ids and two `label for` elements to label range endpoints separately.

## Theme

Component tokens — **45**, all emitted as CSS variables `--apollo-date-picker-*`.

> The table below holds **measured** values from
> `node tests/visual/debug/extract-date-picker-css.mjs --tokens` (antd 6.6.4 default
> theme), not guesses.

| Token | Default |
| --- | --- |
| `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` — the variable name is **`--apollo-date-picker-internal_fixed_item_margin`** (with an **underscore**) |

> ⚠️ There is **one more** variable declared **inside the rules**:
> `--apollo-date-picker-affix-color` (default `inherit`, overridden in the error/warning
> states). It is **not** part of `prepareComponentToken`'s return value. See `README §4`.

## Design notes

### Class prefix and CSS variable namespace are **not** the same

The default class name is **`apollo-picker`** (upstream passes the **literal** `'picker'`
to `getPrefixCls`), while CSS variables are **`--apollo-date-picker-*`** (derived from the
component name `DatePicker`). This mismatch is **upstream behaviour**, not a typo.

### time-picker shares this stylesheet

The `ant-picker` prefix is shared by date-picker and time-picker (upstream does this on
purpose), so this component's stylesheet contains time-picker rules. That is **correct**
(same component family).

### One known difference of static CSS

Values resolved at build time (padding formulas, the `activeShadow` template string,
`lighten(35)` for `cellHoverWithRangeBg`, …) are **inlined as literals** in the static CSS,
so they do **not** follow the primary colour (upstream cssinjs recomputes at runtime).
This is an inherent difference of this repo's "static CSS + CSS variables" architecture,
not a bug; its impact is covered by the L6 theme matrix.


## Basic (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 (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 (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 (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>
```

## Date & Time (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 Hours & Steps (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)

`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 (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)

`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-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>
```

## Labels and input attributes (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)

`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 (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 (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>
```

## Extra Footer (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 with Time (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 (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` 控制浮层相对输入框的落点；空间不足时仍会由触发器自动翻转。

### 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 (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>
```

## Component 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 (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>
```

## Controlled mode (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 (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 and end (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>
```

## Semantic styles (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>
```

## Custom suffix icon (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 (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 (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 (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


Display grouped read-only fields. Each item uses a native `dt` label and `dd` value inside a `dl`. Plain, bordered and vertical layouts share the same content tree.

## Examples

See the 13 paired examples in [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/descriptions/demo). Use DescriptionsItem slots for templates and `items` for programmatic data.

## API

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| prefixCls | Instance DOM prefix; custom prefixes require matching static CSS | `string` | `apollo-descriptions` |
| id | Native root div id | `string` | — |
| bordered | Bordered presentation | `boolean` | `false` |
| size | `default` is deprecated in favor of `large`; `middle` remains supported | `'large' \| 'medium' \| 'small' \| 'default' \| 'middle'` | Provider componentSize, otherwise `large` |
| column | Logical columns; use the largest active breakpoint with a configured value, then the default map | `DescriptionsColumn` | `{ xs: 1, sm: 2, md: 3, lg: 3, xl: 3, xxl: 3, xxxl: 4 }` |
| layout | Label/value arrangement | `'horizontal' \| 'vertical'` | `'horizontal'` |
| colon | Label colon in plain layouts; bordered layouts always hide it | `boolean` | `true` |
| title | Text title; a present #title slot takes priority, including an empty slot | `string` | — |
| items | Data items; even [] takes priority over the default slot without evaluating it | `DescriptionsItemType[]` | — |
| labelStyle / contentStyle | Deprecated; use styles.label / styles.content | `CSSProperties` | — |
| classNames | Classes for the six semantic regions | `DescriptionsSemanticClassNames \| ((info: { props: DescriptionsProps }) => DescriptionsSemanticClassNames)` | — |
| styles | Styles for the six semantic regions | `DescriptionsSemanticStyles \| ((info: { props: DescriptionsProps }) => DescriptionsSemanticStyles)` | — |

Numeric column/span values are floored. A nonfinite value or one below 1 falls back to 3 columns or span 1. Excess spans are clamped to the remaining columns with a development warning. Before media observation (including SSR), column maps fall back to 3 and span maps to 1. Mounted instances then use the current viewport.

### Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| default | DescriptionsItem / Descriptions.Item entries; supports Fragment, v-for and v-if | None |
| title | Complete title content; an intentionally empty slot hides text fallback; 0 remains visible | None |
| extra | Header actions/content, including native buttons and Vue components | None |

Only actual Items become entries; other default-slot nodes are ignored. Both template Items and data items are supported public APIs. There are no business emits or v-models. Native root listeners receive the DOM event once. Empty header content produces no empty shell.

### DescriptionsItemType

| Field | Description | Type | Default |
| --- | --- | --- | --- |
| key | Business identity; provide stable keys for dynamic order | `PropertyKey` | Index |
| label / children | Complete content, including multiple nodes, text, 0, VNodes and Fragments | `VNodeChild` | — |
| span | Logical columns; filled consumes the remainder of the current row and ends it | `number \| 'filled' \| Partial<Record<Breakpoint, number>>` | `1` |
| prefixCls | Item DOM prefix; requires matching CSS | `string` | Parent prefix |
| className / style | Classes/native styles on the owning item div | `string` / `StyleValue` | — |
| classNames / styles | Item label/content regions | `{ label?, content? }` | — |
| labelStyle / contentStyle | Retained deprecated style aliases | `CSSProperties` | — |

Each row's last entry fills its remaining columns. Four items in three columns produce `[1,1,1]` then `[3]`. A(1), B(filled), C(1) produce `[1,2]` then `[3]`; B does not start a separate row.

### DescriptionsItem

The named DescriptionsItem export is the same component as Descriptions.Item. Place it in Descriptions' default slot.

| Prop | Description | Type |
| --- | --- | --- |
| label | Text label; a present #label slot wins, including an empty slot | `string` |
| span / prefixCls | Same as data items | See above |
| classNames / styles | Item label/content classes/styles | `{ label?, content? }` |
| labelStyle / contentStyle | Retained deprecated aliases | `CSSProperties` |
| className | Deprecated; use native class in templates | `string` |

The label and default slots have no arguments and retain complete Vue content. Native class, string/object/array style, id, data, ARIA, tabindex and listeners belong to the item's own div. Parent root attrs stay on the parent. Native controls in content keep their events and keyboard behavior. Item adds no business emits, v-model or expose surface.

### Styling, configuration and lifecycle

Semantic regions are root, header, title, extra, label and content. Root is a div; label/content always target dt/dd. Classes concatenate Provider → component → Item. Region styles resolve Provider → deprecated component styles → component styles → deprecated Item styles → Item styles. Root styles resolve Provider styles.root → Provider style → component styles.root → native Vue style.

ConfigProvider.components.descriptions accepts DescriptionsConfig's className/style/classNames/styles. Global componentSize, direction, prefixCls and theme remain reactive. Semantic callbacks receive `{ props }` with the current effective column and size. Nested instances consume their own configuration; outer region styles do not rewrite inner labels.

Items are normalized in the current render without reactive writes during rendering. Stable business keys preserve Vue instances, native nodes, uncontrolled drafts and owned focus through column/span/order/layout/bordered changes. Removed entries unmount normally; adding them again creates new instances. SSR does not read viewport size; media observation starts after hydration.

### Ref

Only nativeElement: HTMLDivElement | null is exposed. It points to the actual root and clears on unmount. Internal component instances are not exposed.

## Theme (Component Token)

All ten tokens use --apollo-descriptions-* CSS variables. ConfigProvider.theme.components.Descriptions overrides update dynamically and return to current defaults when removed.

| Token | Default | Purpose |
| --- | --- | --- |
| labelBg | colorFillAlter | Bordered label background |
| labelColor | colorTextSecondary | Readable labels in every layout |
| titleColor | colorText | Title text |
| titleMarginBottom | fontSizeSM × lineHeightSM | Header spacing using current font aliases |
| itemPaddingBottom | padding; medium/middle use paddingSM, small uses paddingXS | Item spacing/bordered block padding |
| itemPaddingEnd | padding | Item trailing spacing/bordered inline padding |
| colonMarginRight / colonMarginLeft | marginXS / marginXXS ÷ 2 | Colon inline end/start spacing |
| contentColor | colorText | Value text |
| extraColor | colorText | Header extra text |

Length tokens accept numeric pixels or CSS length strings; color tokens accept strings. Explicit overrides take priority over size defaults, in both plain and bordered layouts. Layout requires modern CSS Grid/Subgrid. Existing semantic classes remain styling hooks; the old table/tr/th/td tree was replaced to preserve Vue content identity. See the [migration notes](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/descriptions-contracts.md).


## Basic (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)

`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 (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>
```

## Custom size (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>
```

## Title & Extra (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 (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` 控制每行列数，通过下拉框切换即可看到条目重新排布。

### 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 (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 (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)

当前组件没有 `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>
```

## Title and extra (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>
```

## Component 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 bordered (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


Separate sections or inline actions, with complete Vue title content, horizontal/vertical axes and current themes.

## Examples

Nine paired demos are in [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 and style-class. The title, component tokens and semantic styles include native controls.

## API

### Props

| Property | Description | Type | Default |
|---|---|---|---|
| prefixCls | Complete component class prefix | string | Current ConfigProvider; apollo-divider fallback |
| orientation | Axis; legacy title positions remain accepted with a warning | Orientation \| TitlePlacement | Effective horizontal |
| vertical | Vertical axis; explicit false overrides type | boolean | undefined when omitted |
| titlePlacement | Logical start/end, center, or physical left/right | 'start' \| 'end' \| 'center' \| 'left' \| 'right' | center |
| plain | Body typography for the title | boolean | false |
| variant | Line style; dotted takes precedence over the dashed boolean | 'solid' \| 'dashed' \| 'dotted' | solid |
| dashed | Dashed fallback, combinable with variant | boolean | false |
| size | Horizontal spacing; medium/middle are equivalent; ignored vertically | 'small' \| 'medium' \| 'middle' \| 'large' | Current componentSize |
| classNames | Semantic classes or a callback | DividerSemanticValue<DividerSemanticClassNames> | — |
| styles | Semantic styles or a callback | DividerSemanticValue<DividerSemanticStyles> | — |
| ~~type~~ | Legacy axis; use orientation | Orientation | — |
| ~~orientationMargin~~ | Length from the closest title edge at start/end; prefer styles.content.margin in new code | string \| number | — |

Orientation is horizontal / vertical; TitlePlacement contains the five title positions. Axis precedence is a valid orientation → explicit vertical → type → horizontal. Legacy orientation title values do not set the axis and emit a migration warning.

Physical left/right follow the current Provider direction or native root ltr/rtl dir; a native dir takes precedence. Small spacing uses marginXS, medium/middle use margin, and large retains standard spacing (marginLG for a plain rail, margin for a titled divider).

orientationMargin converts numbers and decimal numeric strings, including signs/fractions, to px. CSS unit strings and zero remain valid; center ignores this field. This prop is a length; the component token with the same name is a ratio from 0 to 1.

### Native attrs, events and ref

The single root is a div: separator without a title or in vertical mode, and group with a horizontal title. The empty start rail is a separator; the other rail is hidden decoration, so native title controls are not nested inside an interactive role. Vue class/style, id, ARIA and native listeners reach the current root; class accepts strings/arrays/objects and style accepts strings/objects/arrays. Native style has final priority. Vertical roots declare aria-orientation=vertical; horizontal roots use the separator default. Roles follow this actual content structure.

There are no business emits, v-model or internal keyboard commands. Slotted inputs, links and buttons retain native interaction and focus. nativeElement exposes the actual div, null before mount/after unmount.

### Content and semantics

The default slot is `() => VNodeChild`, including text, zero, arrays/Fragments and elements. Conditional slot insertion/removal updates the title immediately; an intentionally empty slot still represents a title. Vertical mode ignores title content with a warning.

Semantic areas are root, rail and content. Rail targets the root without a title and the two rails with a horizontal title. Classes concatenate. Style order is Provider styles → Provider style(root) → local styles → native root style. Callbacks receive `{ props }` with current effective orientation, titlePlacement and size.

ConfigProvider divider / components.divider provides className, style, classNames and styles defaults. Local size wins over current componentSize. Replacing or clearing configuration does not require remounting.

### Component tokens and themes

| Token | Default | Meaning |
|---|---|---|
| textPaddingInline | 1em | Horizontal title padding; numeric lengths use px |
| orientationMargin | 0.05 | Closest rail fraction; finite number from 0 to 1 |
| verticalMarginInline | Current marginXS | Horizontal margin of a vertical rail; numeric lengths use px |

```vue
<ConfigProvider :theme="{ components: { Divider: { textPaddingInline: 12, orientationMargin: 0.2, verticalMarginInline: 16 } } }">
  <Divider title-placement="start">Section</Divider>
  <Divider orientation="vertical" />
</ConfigProvider>
```

All three update and reset dynamically. Empty/nonfinite values use their own defaults; padding rejects negative numbers and margin accepts negative lengths. The nearest active ThemeProvider/ConfigProvider is consumed. ThemeProvider works without global CSS injection; an explicit empty ThemeProvider resets defaults. An empty ConfigProvider theme inherits its outer source; use inherit: false to reset it. Without a theme source, consumer CSS inheritance is retained. Default, dark, compact and nested scopes are supported.

### Exports and styles

The root exports Divider, DividerProps, DividerRef, DividerConfig, DividerSize, DividerVariant, Orientation, TitlePlacement, semantic types and DividerSlot. `@apollo-design/ui/divider` additionally provides default, DividerComponentToken, genDividerStyle and prepareDividerComponentToken. The installation name is ADivider.

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

Static CSS covers apollo by default. Pre-generate/load CSS for another namespace: genDividerStyle('my-app') corresponds to ConfigProvider prefixCls=my-app or Divider prefixCls=my-app-divider. The generator takes a namespace, while the component prop takes a complete prefix; selectors are not generated at runtime.


## Horizontal (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 (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)

`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` 让标题使用正文颜色、字号和字重。文本、具名根样式和当前主题仍正常生效。

### 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 (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 (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>
```

## Component 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 (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 (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


A panel that slides in from the edge of the screen.

## When to use

- When a large amount of content (or a form) should slide in from an edge.
- When it must render **inside the current node** (`:get-container="false"`) instead of body.
- When a resizable (`resizable`) or nested (child pushes parent) drawer is needed.

## Demos

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/drawer/demo) for the 18 existing scenarios.

## API

| Property | Description | Type | Default |
|---|---|---|---|
| open | Whether visible | `boolean` | `false` |
| placement | Placement | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` |
| size | Preset or explicit size | `'default' \| 'large' \| number \| string` | `'default'` (378) |
| defaultSize | Default size (**the source of the vertical default**) | `number` | `378` |
| maxSize | Maximum size while resizing | `number` | — |
| title | Title (text; rich title via `#title` slot, slot first) | `string` | — |
| footer | Footer (⚠️ moved to `#footer` slot; empty slot = hidden) | `slot` | — |
| extra | Header-right area (⚠️ moved to `#extra` slot) | `slot` | — |
| closable | Close button; `false` removes it; object supports `placement: 'start' \| 'end'` | `boolean \| null \| {...}` | `true` |
| closeIcon | Custom close icon (⚠️ moved to `#closeIcon` slot) | `slot` | — |
| loading | Skeleton in the body | `boolean` | `false` |
| mask | Mask; `false` adds `no-mask` to the root | `boolean \| { enabled?, blur?, closable? }` | `true` |
| maskClosable | Close on mask click (⚠️ deprecated ⇒ `mask.closable`) | `boolean` | `true` |
| push | Push: `true` / `{ distance }` (**only a child drawer actually pushes**) | `boolean \| PushState` | `{ distance: 180 }` |
| resizable | Drag to resize; notifications use Vue events below | `boolean` | `false` |
| getContainer | Container; false renders inline, other values follow Portal | `GetContainer` | Default container under body |
| destroyOnHidden | Unmount when closed | `boolean` | `false` |
| forceRender | Mount hidden content without joining the active Escape stack | `boolean` | `false` |
| focusable | Focus return and trap; explicit trap wins, otherwise enabled for masked non-inline drawers | `{ focusTriggerAfterClose?, trap? }` | — |
| focusTriggerAfterClose | Override the focus-return setting in focusable | `boolean` | `true` |
| keyboard | Close on ESC | `boolean` | `true` |
| autoFocus | Focus the panel on open | `boolean` | `true` |
| rootStyle | Root styles; native style has higher priority | `CSSProperties` | — |
| zIndex | Explicit root stacking level; otherwise follows current theme and nesting | `number` | — |
| classNames / styles | 12 semantic slots | — | — |

`open` is controlled. Buttons, mask clicks and Escape emit requests; the parent updates `open` when it accepts the request. `destroyOnHidden` waits for the leave motion to finish. Conditional unmounts also release focus locks, drag listeners and push registrations.

Explicit size (including the width/height alias for the current axis) stays controlled: dragging emits a size request. Without it, resizing updates the local default size. Removing controlled size preserves the last accepted value and discards refused requests.

### Events

| Event | Description | Payload |
|---|---|---|
| close | Close button, mask click or active-layer Escape request | Original `Event` (MouseEvent / KeyboardEvent) |
| afterOpenChange | Enter or leave motion completed | `open: boolean` |
| resizeStart | Drag started | `size: number`, pixels |
| resize | Current resized dimension | `size: number`, pixels |
| resizeEnd | Measured dimension after a normal drag end | `size: number`, pixels |

Events support Vue `.once` and listener arrays. Closing, disabling resizing, changing placement or unmounting releases drag listeners without reporting a normal drag end.

**Deprecated (9, dev warnings)**: `headerStyle` / `bodyStyle` / `footerStyle` → `styles.*`;
`contentWrapperStyle` → `styles.wrapper`; `maskStyle` → `styles.mask`; `drawerStyle` →
`styles.section`; `destroyOnClose` → `destroyOnHidden`; `width` / `height` → `size`.

Content slots are typed through `DrawerSlots` and take precedence when present, including empty content. Each Drawer render evaluates the title once; panel content and automatic `aria-labelledby` share that snapshot. An explicit external `aria-labelledby` is preserved. Header/footer visibility changes preserve the body DOM and input state.

`getContainer` uses Portal’s full `GetContainer` contract, including `false`, selectors, elements and container functions. Vue templates can use `:get-container="false"` directly. Drawer routes native class/style (including arrays, objects and strings), data attributes and ordinary DOM events to its outer root. The actual dialog owns id, role and ARIA. Customize the panel with `classNames.section` / `styles.section`. PurePanel owns all of its native root attrs.

### Template refs and development migration

`DrawerRef` exposes `nativeElement: HTMLElement | null` and `focus(options?: FocusOptions)` for the current outer root. The element can be null before mounting or after destruction. Use a real Vue template ref:

```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>
```

In this unpublished development version, replace `:after-open-change="fn"` with `@after-open-change="fn"` (`onAfterOpenChange` in `h()`), and replace `:resizable="{ onResize, onResizeStart, onResizeEnd }"` with `resizable` and the three corresponding events. The unused `DrawerResizableConfig`, `panelRef` and `destroyInactivePanel` are removed: use `DrawerRef` for DOM access and `destroyOnHidden` for destruction. PurePanel types no longer claim to consume internal `ariaId`, `size` or `contentWrapperStyle`. Native class/style now target the root; move panel customization to the section semantic fields. There is no compatibility layer or deprecation period for these corrections. Existing documented style and destruction aliases remain supported.

## Theme (Component Token)

4 tokens (CSS variables `--apollo-drawer-*`): `zIndexPopup` (= `zIndexPopupBase` = **1000, no
offset**) / `footerPaddingBlock` (8) / `footerPaddingInline` (16) / `draggerSize` (4).

Drawer and PurePanel read current `ConfigProvider.components.drawer` className/style, classNames/styles and applicable closable/mask/focusable settings. Instance semantic styles override Provider styles; native root style wins last. Configure the four tokens with `theme.components.Drawer`. Consumed aliases, nesting, replacement and removal update the current root CSS variables; explicit zIndex still wins. The component-token and config-provider demos include live switches.

## Design notes

### The size axis follows the placement

`left`/`right` use **width**; `top`/`bottom` use **height**. Presets: `'large'` = 736,
`'default'` = 378. ⚠️ rc's 378 fallback only applies to horizontal placements — the vertical
default comes from `defaultSize`.

### The push chain of nested drawers

Each open child owns a push registration. The parent returns only after all children close or unmount, and translates by `push.distance` (180 by default, CSS length strings supported). A top-level drawer stays in place until a child opens.


## basic-right (basic-right)

Basic drawer.

### 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 demo.

### 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)

Toggle four component tokens while open to update footer spacing, the resize handle and stacking.

### 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)

Replace or remove Provider configuration while open to update the close button, body spacing and footer styles.

### 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)

Use `#extra` slot to set the action area of the header.

### 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)

A contact form inside a drawer, with required-name and email validation and submit actions in the footer. Invalid input stays open; a valid submission closes the drawer and displays local feedback. Reopening starts a clean form. This example does not send a network request.

### 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 demo.

### 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 demo.

### 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)

Nested drawers: opening the child pushes the parent.

### 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 demo.

### 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)

The Drawer can appear from any edge of the screen.

### 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)

With `getContainer={false}` the drawer renders inline instead of being portaled.

### 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 demo.

### 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)

A resizable drawer with current size reported through `resize`, `resizeStart` and `resizeEnd`, bounded by `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 demo.

### 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)

Drawer size: `default` (378px) or `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 demo.

### 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)

Display a sample user's personal and work details in a drawer with Avatar and Descriptions. The panel fits the available width and can be closed from its footer or header, then reopened with the same static profile.

### 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


Place actions in a menu attached to a trigger. Menu owns item data, selection and keyboard navigation; use the named slot for custom popup content.

## Dropdown props

| Prop | Behavior | Default |
| --- | --- | --- |
| menu | Current MenuProps, including items, selection and Menu events | — |
| open / defaultOpen | Controlled v-model:open / initial uncontrolled value | false |
| trigger | An array of click, hover and contextMenu; overrides Provider defaults | hover |
| disabled | Uses global disabled when omitted; explicit false overrides it | — |
| placement | DropdownPlacement; legacy Center values normalize to top/bottom | bottomLeft, bottomRight in RTL |
| arrow | Boolean or `{ pointAtCenter }` | false |
| mouseEnterDelay / mouseLeaveDelay | Current delays in seconds | 0.15 / 0.1 |
| autoAdjustOverflow | Adjust overflow | true |
| getPopupContainer | Current HTMLElement / ShadowRoot popup container; falls back to Provider | body |
| destroyOnHidden / forceRender | Destroy after leave / prerender | false |
| transitionName | Override the existing directional motion name | Based on placement |
| zIndex | Explicit numeric layer, including 0 | Current Token or parent plus offset |
| classNames / styles | root, item, itemTitle, itemIcon, itemContent; object or `({ props }) => object` | — |
| rootClassName / overlayClassName / overlayStyle / destroyPopupOnHide | Existing aliases; prefer semantic fields and destroyOnHidden | — |

Semantic functions read current resolved configuration and open state. root belongs to the actual popup root. The four item regions reach Menu and merge with menu.classNames/styles; Dropdown styles take precedence for matching fields. Styles use Vue CSSProperties, including undefined and CSS custom properties.

Native class/style, id, ARIA and native listeners belong to the trigger. A single element/component retains its node; text, multiple nodes and Fragments use a stable span. Popup appearance belongs to styles.root/classNames.root. Provider class/style, semantics, arrow, trigger, delays and the global container remain current.

## Events

| Event | Payload |
| --- | --- |
| update:open | `(open: boolean)` |
| openChange | `(open: boolean, info: { source: 'trigger' or 'menu' })` |
| afterOpenChange | `(open: boolean)`, after actual motion completion |

Vue listener arrays, replacement and .once are supported. Menu selection emits each notification once; selectable multiple menus stay open. Controlled close requests do not change a rejected value, and withdrawal keeps the last accepted state. Replace the old afterOpenChange function prop with @after-open-change, or onAfterOpenChange in h/JSX. There is no compatibility callback channel.

## Slots and refs

| Slot | Scope / behavior |
| --- | --- |
| default | Complete trigger content |
| popupRender | `{ originNode: VNodeChild }`; a present slot overrides the menu, including empty content |

DropdownRef keeps forceAlign(), nativeElement() and popupElement(). DOM getters return the current HTMLElement or null. Closed DOM retention follows destroyOnHidden.

## DropdownButton

Apollo supports this composition. It retains split, type, size, loading, danger, disabled, href, target, menu, placement, trigger, arrow, open, container and layer configuration. The main button triggers the menu when split is false. In split mode, the main button emits click and the right button independently opens the menu. target applies to the main link; native attrs and class/style belong to the group root.

Events are click(MouseEvent), openChange(open, info) and update:open, including v-model:open. The default slot keeps all main-button content. The current icon slot keeps all nodes; an intentionally empty slot hides the fallback icon. buttonsRender receives `{ buttons: [main VNode, trigger VNode] }` and returns the two corresponding Vue children. popupRender uses the Dropdown scope. DropdownButtonRef keeps nativeElement(), returning the actual Dropdown trigger.

The icon prop/function channel already migrated to #icon and its unused interface field is removed. Dropdown.Button and Dropdown._InternalPanelDoNotUseOrYouWillBeFired remain typed component aliases.

## PurePanel and theme

DropdownPurePanel displays the same Menu in document flow. It accepts menu, classNames/styles, popupRender and native class/style. Native strings, objects and arrays override semantic root styles; current Provider and theme values also apply.

The seven existing CSS fields are zIndexPopup (1050), paddingBlock (5), arrowOffsetHorizontal, arrowOffsetVertical, arrowShadowWidth, arrowPath and arrowPolygon. Current marginXXS, sizePopupArrow and borderRadius feed CSS and positioning together. Nested and explicit layers follow the existing numeric protocol. Non-numeric CSS expressions retain their style value but do not participate in automatic descendant numeric stacking.


## arrow (arrow)

You could display an 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)

Set the arrow to point at the center of the target element.

### 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)

Move the mouse over and a dropdown menu will appear.

### 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)

Extend the menu with 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)

A click event on the menu item.

### 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)

Support additional node display (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)

Six placement options available for buttons.

### 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 displays the same menu composition in document flow, with the current theme and native 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)

The menu items are 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)

Multiple selectable menu items.

### 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)

Use separate semantic regions for the popup root and menu content; switch the current menu spacing and layer.

### 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 menus of the 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)

Support click and contextMenu 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


A placeholder for an empty data region. Use the footer slot for actions such as creating the first item.

## When To Use

- Explain an empty list, table, or business region.
- Supply complete image, description, and footer content through native Vue slots.

## Examples

Six demos cover default/simple illustrations, complete custom content, current Provider settings, conditional descriptions, and all four semantic regions.

## API

### Props

| Property | Description | Type | Default |
|---|---|---|---|
| prefixCls | Full component prefix | `string` | `apollo-empty`, follows ConfigProvider |
| image | A top-level string is an image URL; accepts components, VNodes, arrays and numbers. Only undefined falls back; null, booleans and empty content hide the image host | `EmptyImage` | Provider image or `PRESENTED_IMAGE_DEFAULT` |
| imageStyle | Existing deprecated field: use styles.image. Both merge, with styles.image taking priority | `CSSProperties` | — |
| description | Complete Vue content; only undefined uses the current locale. Empty content hides its host, while numeric 0 remains | `VNodeChild` | Current locale Empty.description |
| classNames | Classes for four semantic regions; factories receive current local props | `EmptySemanticValue<EmptySemanticClassNames>` | — |
| styles | Styles for four semantic regions; factories receive current local props | `EmptySemanticValue<EmptySemanticStyles>` | — |

The native root accepts Vue class/style/dir, data/ARIA attributes and native event listeners. Native style supports strings, objects and arrays, and overrides styles.root. There are no business emits or v-model bindings.

### Slots

| Name | Description |
|---|---|
| image | Complete image content, overriding image and Provider defaults; custom content uses its natural height |
| description | Complete description, overriding the prop and locale fallback |
| default | Complete footer content, including multiple business controls |

Each slot is evaluated once during the current render. A present slot takes priority even when intentionally empty. Empty arrays, comments, booleans and empty Fragments create no spacing host. Business descendants retain their own attributes, editing state and focus.

### Provider and semantic regions

`ConfigProvider :components="{ empty }"` accepts a named `EmptyConfig` with image, className, style, classNames and styles. Configuration updates and removal remain reactive. Provider semantic settings use objects.

The four regions are root, image, description and footer. Classes merge from Provider to local semantic classes and native root class. Root style priority is:

```
Provider styles.root → Provider style → local styles.root → native root style
```

Local semantic styles override Provider styles for other regions. The legacy imageStyle has lower priority than styles.image. Fixed media height and opacity apply to built-in illustrations and URL images; complete custom content retains its layout and colors. Current Provider direction applies unless overridden by native dir.

### Static values, types and ref

`Empty.PRESENTED_IMAGE_DEFAULT` and `Empty.PRESENTED_IMAGE_SIMPLE` are also named exports. Root and `@apollo-design/ui/empty` imports share their identity. These reusable component definitions render normally through Vue. The actual simple component or its VNode enables normal mode; lookalike custom artwork does not.

Exported types: EmptyProps, EmptySlots, EmptyImage, EmptyRef, EmptyConfig, EmptySemanticClassNames, EmptySemanticStyles, EmptySemanticValue, EmptySemanticType, EmptySemanticAllType.

| Expose | Type | Description |
|---|---|---|
| nativeElement | `HTMLDivElement \| null` | Actual root div; null before mount and after unmount |

URL image alt uses a string description, otherwise the current localized empty-state description. Built-in illustration titles update with the locale and retain accessible names in image-only states.

### Theme and CSS

Empty has no Component Token. Layout uses existing Alias Tokens. Illustration palettes derive from the current theme at runtime; generated geometry and source attribution are preserved. Default description text uses colorTextSecondary.

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

Static CSS includes the apollo root prefix. For a custom root prefix my-app, set ConfigProvider prefix-cls to my-app and load CSS from `genComponentCss('empty', 'my-app')`. A direct component prefixCls receives the full value, such as my-app-empty.


## Basic (basic)

最简单的用法：默认插画 + 默认描述（来自 locale，`en_US` 是 `No data`）。

### basic.vue

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

<template>
  <Empty />
</template>
```

## Simple (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 (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)

保留字符串描述、关闭描述和完整节点三个场景。#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>
```

## ConfigProvider (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 (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 aligns and spaces complete Vue content directly, without adding a wrapper around every child. Use Space when each inline item needs its own spacing wrapper.

## Examples

The six paired demos show direction, alignment, gaps, wrapping, a responsive project summary and layout blocks. Their native controls have labels and retain normal keyboard behavior.

## API

| Prop | Description | Type | Default |
|---|---|---|---|
| prefixCls | Complete class prefix; custom prefixes require matching consumer CSS | `string` | Current ConfigProvider, then `apollo-flex` |
| vertical | Vertical direction; omission permits current `flex.vertical` config | `boolean` | `undefined` |
| orientation | Takes precedence over `vertical` and Provider | `'horizontal' \| 'vertical'` | Resolved direction defaults to horizontal |
| wrap | Multiple lines; true means wrap | `boolean \| 'wrap' \| 'nowrap' \| 'wrap-reverse'` | Single line |
| justify | Main-axis CSS alignment | `FlexJustify` | Native flex-start behavior |
| align | Cross-axis CSS alignment | `FlexAlign` | Horizontal: flex-start; vertical: stretch |
| flex | CSS shorthand; numbers are unitless | `string \| number` | — |
| gap | Pixel number, CSS length or preset | `'small' \| 'medium' \| 'middle' \| 'large' \| string \| number` | — |
| component | Native tag or Vue component forwarding attrs/default slot to its host | `Component \| string` | `'div'` |

Direction priority is `orientation` → explicit `vertical` → current ConfigProvider `flex.vertical` → horizontal. ConfigProvider `flex.className`, `flex.style`, vertical, direction and prefix updates are read at render time. Explicit native `dir` wins over Provider direction.

### Slots, events and state

`#default` accepts complete Vue content, including zero, text, multiple VNodes and Fragments. Flex has no business emits or v-model. Native root listeners receive their original DOM events once. Caller-owned inputs, links and buttons keep their own semantics, focus and keyboard behavior.

Root `class`, `style`, id, data/ARIA attributes, tabindex and native listeners use Vue attrs. Styles accept Vue strings, objects and arrays. Priority is current theme aliases → Provider `flex.style` → native `style` → derived `flex`/non-preset `gap`. Changing appearance keeps the host and keyed children; changing `component` replaces its owned host normally. Empty roots stay mounted and retain their layout and native semantics.

### Ref

| Name | Type | Description |
|---|---|---|
| nativeElement | `HTMLElement \| null` | Actual single HTML host, including a Vue component's root; null before mount, after unmount or when no single HTML host exists |

Custom components own their slot/attrs forwarding. Flex exposes their actual HTML host rather than their component instance; Fragment, text-only and non-HTML roots have no `nativeElement`.

## Theme

Flex has no component tokens. Gap presets consume current `paddingXS` (small), `padding` (medium/middle) and `paddingLG` (large). The three alias variables are scoped on Flex when a ThemeContext is supplied, so ThemeProvider works without global CSS injection and nested default themes reset their own gaps. Native custom properties can override these aliases locally. Zero and fractional pixel gaps are supported.


## Basic (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)

使用原生下拉控件改变主轴与交叉轴对齐。横向默认顶部对齐，纵向默认拉伸。

### 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)

三档预设消费当前主题别名；自定义滑块支持零间距，并在条件出现时保留独立名称。

### 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 (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 (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>
```

## Layout blocks (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


A floating action at the edge of a page, optionally grouped or used to return to the top.

## When To Use

- Global actions such as back to top, support and feedback.
- Related actions collected in `FloatButtonGroup`.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/float-button/demo) for all 14 examples.

## API

### FloatButton

| Prop | Description | Type | Default |
|---|---|---|---|
| type | Button type | `'default' \| 'primary'` | `'default'` |
| shape | Shape; inherits the Group shape | `'circle' \| 'square'` | `'circle'` |
| disabled | Disabled; inherits ConfigProvider when omitted | `boolean` | `false` |
| href / target | Link URL and browsing target; href renders an anchor | `string` | — |
| htmlType | Native button type | `'button' \| 'submit' \| 'reset'` | `'button'` |
| aria-label | Accessible button name | `string` | — |
| tooltip | Tooltip content or configuration | `string \| TooltipProps` | — |
| badge | Badge configuration without status, text, title or children | `FloatButtonBadgeProps` | — |
| description | Deprecated; use `#content` | `string` | — |
| prefixCls | Complete class prefix | `string` | `'apollo-float-btn'` |
| classNames / styles | root, icon and content semantics; accepts `({ props }) => ...` | `FloatButtonProps['classNames' / 'styles']` | — |

`#icon` supplies complete icon content. Without an icon slot, empty content uses the default icon. `#content` supplies complete content; use `shape="square"` for text. Slot presence takes precedence, including intentionally empty results. Dynamic slots, text, arrays and Fragments update during rendering. FloatButton has no default slot or model.

`@click` emits the original `MouseEvent` once. Disabled controls follow Button's native activation rules.

Native class, style, id, ARIA and listeners reach the actual button/anchor. Style accepts Vue strings, objects and arrays. Precedence is current theme, Provider root style, semantic root style, then native style. An explicit zIndex, including zero, is preserved.

### FloatButtonGroup

| Prop | Description | Type | Default |
|---|---|---|---|
| trigger | Menu trigger; omit to display the list directly | `'click' \| 'hover'` | — |
| open | Controlled state; supports `v-model:open` | `boolean` | Uncontrolled starts closed |
| placement | List placement | `'top' \| 'left' \| 'right' \| 'bottom'` | `'top'` |
| shape | List and trigger shape; circle uses Flex, square uses Space.Compact | `'circle' \| 'square'` | `'circle'` |
| type / disabled / href / target / htmlType / tooltip / badge / aria-label | Trigger configuration; child buttons declare their own properties | As FloatButton | — |
| prefixCls | Complete class prefix | `string` | `'apollo-float-btn'` |
| classNames / styles | root, list, item, itemIcon, itemContent, trigger, triggerIcon, triggerContent | Object or `({ props }) => object` | — |

| Event | Payload | Description |
|---|---|---|
| update:open | `boolean` | Proposed state for `v-model:open` |
| openChange | `boolean` | Emitted once alongside update:open |
| click | `MouseEvent` | Original trigger activation |

`#default` supplies the list. `#icon`, `#closeIcon` and `#content` supply the trigger's closed icon, open icon and content. Trigger and list buttons consume their respective semantic regions.

Native Group attrs reach its outer div once. Configure the trigger with the listed props and trigger semantics. Controlled proposals change the state only when accepted by the parent; removing control retains the last accepted value. Click menus close on outside clicks. Hover menus also support focus entry and native button activation. Escape requests closing. An accepted close returns focus from the list to the trigger; rejected closes and external focus keep their current focus.

### FloatButtonBackTop

Inherits FloatButton props, `#icon` / `#content` and `@click`, with target replaced by a scroll-container getter.

| Prop | Description | Type | Default |
|---|---|---|---|
| visibilityHeight | Visible at or beyond this scroll offset | `number` | `400` |
| duration | Scroll animation duration in milliseconds; zero or less is immediate | `number` | `450` |
| showProgress | Show scroll progress | `boolean` | `false` |
| target | Current scroll container; a pending ref may return null | `() => HTMLElement \| Window \| Document \| null` | Button's owner document |

Target, threshold and progress options update reactively. Repeated clicks, target changes and unmounting cancel the current scroll animation. Reduced motion and theme `motion: false` scroll immediately. Scroll/resize listeners are released with their target and owner window.

### Provider and theme

`ConfigProvider.components.floatButton` and `floatButtonGroup` provide className, style, classNames and styles. Replacement, removal, nested scopes, prefixCls and direction follow their current values. FloatButton has no component tokens; size, spacing, color, shadow and motion consume current global Alias Tokens.

### Expose

FloatButton and FloatButtonBackTop expose readonly `nativeElement: HTMLButtonElement | HTMLAnchorElement | null`; Group exposes `HTMLDivElement | null`. A hidden or unmounted BackTop may expose null. No additional imperative methods are provided.


## Basic (basic)

The most basic usage (default `FileTextOutlined` icon). `position: fixed` is relative to the viewport, so this demo is rendered inside a viewport canvas.

### 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 (group)

`FloatButtonGroup` (circle via Flex; square via Space.Compact). It is positioned against the viewport as well.

### 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 (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 (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)

The `badge` data prop.

### 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)

The `#content` slot (successor of the 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)

Controlled `open` (used with `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 mode via `trigger`.

### 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)

Menu placement.

### 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)

Progress ring via `showProgress`.

### 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)

Two shapes.

### 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)

Semantic `classNames` and `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)

The `tooltip` data prop (string or TooltipProps object).

### 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)

Two types with the `#icon` slot.

### 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

See `index.zh-CN.md` for full API tables. Key notes:

- first UI consumer of `@apollo-design/form-core` (store/Field/List live in the foundation package);
- value channel: control receives `value` (valuePropName) + `onChange` synthesized to Vue `onUpdate:value` (v-model bridge);
- `getFieldId` = namePath.join('_') with form `name` prefix; `parentNode` is blacklisted;
- explicit rule `message` wins over `validateMessages` templates;
- error list debounce: 0ms when has content / 10ms when cleared (antd verbatim);
- `aria-describedby` / `aria-invalid` / `aria-required` are injected on the control (antd verbatim).

The Form default slot receives `{ values, form }`; enable `render-props` when the whole slot reads current store values. Fields keep their metadata and reset subscriptions in both modes, including forms created with `useForm()` outside the container.

Form.Item receives `{ control, meta, form }` in both bound and layout modes. A standalone layout item has an empty control/metadata and `form: undefined`. Its `reset()` and `metaChange(meta)` notifications are Vue emits. Form.List keeps its existing `{ fields, operations, meta }` scope, including stable `fieldKey` values.

In development version `0.0.0`, replace positional Form / Form.Item slot arguments with the named object directly; there is no compatibility layer or deprecation period. Validators, value extraction, normalization and asynchronous business callbacks retain their function contracts. `useWatch(pathOrSelector, form)` or `useWatch(pathOrSelector, { form, preserve })` returns a Ref and releases its subscription with the calling effect scope.

`nativeElement` returns the actual HTML container or null for a containerless/fragment host.

Use `#requiredMark="{ label, required }"` for custom mark content and render the stable original-label component with `<component :is="label" />`. The primitive `requiredMark` prop accepts `boolean | 'optional'`. Custom feedback uses `#feedbackIcon="{ status, errors, warnings }"` on Form or Form.Item, with Item priority and live slot withdrawal. In development, replace the former requiredMark content callback, feedbackIcons and hasFeedback.icons directly with these slots; hasFeedback is boolean.

Form.Item implements `label`, `help`, `extra`, `tooltip` and `feedbackIcon` slots. Explicit empty slots override their corresponding props. Tooltip help is a keyboard-focusable native button beside the associated label. Form and styled Form.Item forward native attrs/class/style to their actual root. Form.List and noStyle items have no DOM root. Nested items stop inheriting outer label/wrapper column widths.

`useFormInstance()` reads the nearest existing Form instance and returns undefined outside Form. Repeated useForm calls and a Form receiving the same external store share one actual instance and control registry. `getFieldInstance(name)` returns the actual DOM/component public ref as `object | undefined`; custom expose objects need not have a focus method. `focusField(name)` uses the control’s real focus capability; `scrollToField(name, { focus: true })` scrolls its actual element and focuses when supported. `scrollToFirstError=false` disables automatic scrolling.

All eleven Form component Tokens, including inlineItemMarginBottom, read current `ConfigProvider theme.components.Form`, including replacement and removal. Standalone Form.Item uses the same theme. Native style CSS variables keep local precedence; custom prefixes require matching preloaded static CSS. Semantic classNames/styles merge Provider defaults with local values and receive resolved current Form props. Form disabled=false overrides an outer disabled Provider.

Form.ErrorList forwards native attrs to its actual help root and owns `visibleChanged(visible: boolean)`. Duplicate messages retain separate rows. Leaving rows keep their last content until motion completes, then the measured placeholder is released.

Dynamic `prefixCls` and layout changes update derived classes, feedback icons in real controls, error/help content and the measured margin placeholder. Standalone `Form.ErrorList` reads ConfigProvider’s prefix; inside Form.Item / Form.List it follows the nearest prefix context. Preload static CSS for every custom prefix; changing the prefix does not generate runtime styles.


## Dynamic 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>
```

## Nested Dynamic Form (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>
```

## Watch Field (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 (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 (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 & Reset (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 (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 & Get Values (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 (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 (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 (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 (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>
```

## Component 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>
```

## Form methods (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 (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 (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 rules (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-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-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-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>
```

## Label wrap (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>
```

## Multiple layouts (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 (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>
```

## Nested messages (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 (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>
```

## Semantic styles (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 (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 (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 (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 instance (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


A 24-column layout. Row creates a flex row; Col controls width, order, logical offsets and flex sizing. Nested rows own their gutters. Wrapper components may forward slots and injection normally.

## Examples

The 13 actual demos in [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/grid/demo) cover columns, independent two-axis gutters, offsets/order, six main-axis alignments, four cross-axis alignments, flex, responsive layouts and native range controls. Demo colors follow the current theme.

## API

### Row

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| gutter | Nonnegative spacing: numbers in px or valid CSS length strings. Both tuple axes accept breakpoint maps | `ResponsiveValue<number \| string> \| readonly [ResponsiveValue<number \| string>, ResponsiveValue<number \| string>]` | `0` |
| justify | Main-axis alignment, optionally responsive | `ResponsiveValue<'start' \| 'end' \| 'center' \| 'space-around' \| 'space-between' \| 'space-evenly'>` | — |
| align | Cross-axis alignment; stretch explicitly stretches column boxes | `ResponsiveValue<'top' \| 'middle' \| 'bottom' \| 'stretch'>` | — |
| wrap | Wrap unless explicitly false | `boolean` | `true` |
| prefixCls | Root class prefix; custom prefixes require corresponding static CSS | `string` | Provider prefix + `-row`, normally `apollo-row` |

`ResponsiveValue<T> = T | Partial<Record<Breakpoint, T>>`.

### Col

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| span | Integer from 0 to 24; 0 hides the column | `number` | — |
| order | Visual order, integer 0–24 | `number` | — |
| offset | Margin at inline start, in integer columns 0–24 | `number` | — |
| push / pull | Logical inline-start/end positional shifts, in integer columns 0–24 | `number` | — |
| flex | auto→`1 1 auto`; number n→`n n auto`, including 0/fractions; px/em/rem/% length→`0 0 length`; other valid flex strings pass through | `string \| number` | — |
| xs / sm / md / lg / xl / xxl / xxxl | Numeric span shorthand, or ColSize with optional span/order/offset/push/pull/flex | `number \| ColSize` | — |
| prefixCls | Root class prefix; custom prefixes require corresponding static CSS | `string` | Provider prefix + `-col`, normally `apollo-col` |

### Default slot, native attributes and refs

Both default slots have no scoped arguments and accept complete Vue content: text, 0, multiple nodes, Fragments and components. There are no business emits or v-model bindings. Each root is a stable div. Native id/class/style/ARIA/tabindex and DOM listeners belong to that root. Listeners fire once. Vue string/object/array styles update and clear normally.

- Row style precedence: gutter geometry → Provider row.style → native style.
- Col style precedence: gutter/flex geometry → Provider col.style → native style → responsive flex variables. Native style may override geometry; span/flex still determine used width through CSS layout.
- `ref<GridRef>` exposes `nativeElement: HTMLElement | null`, pointing to the actual div and clearing on unmount. Layout updates preserve native child state. Row/Col add no keyboard behavior or focus stops. Hiding focused content with span=0 follows normal browser focus behavior.

### Provider

`ConfigProvider :components="{ row: rowConfig, col: colConfig }"` accepts RowConfig/ColConfig with `className?: string` and `style?: CSSProperties`. Configuration, direction and prefix remain current across replacement/removal. Provider direction supplies the default native dir; explicit root dir or CSS direction may override it. Nested Providers and independent instances keep their own configuration.

### Breakpoints and hook

| Breakpoint | Col static CSS | useBreakpoint / Row responsive values |
| --- | --- | --- |
| xs | Base rules until overridden at a larger breakpoint | ≤575px |
| sm | ≥576px | ≥576px |
| md | ≥768px | ≥768px |
| lg | ≥992px | ≥992px |
| xl | ≥1200px | ≥1200px |
| xxl | ≥1600px | ≥1600px |
| xxxl | ≥1920px | ≥1920px |

All Col classes are present together; CSS applies from smaller to larger breakpoints. Explicit zero values reset smaller-breakpoint offsets/order. Removing a breakpoint restores underlying active rules. Row justify/align/gutter select the largest currently matching configured breakpoint. No match leaves the value unset: gutter `{ xs: 8, md: 24 }` has no active entry at 576–767px.

`useBreakpoint(refreshOnChange?, defaultScreens?)` returns `Ref<Screens | null>`. A false boolean/getter pauses publication while caching media changes. When a getter becomes true, the current viewport is published immediately. Use `() => enabled.value` for a dynamic switch. Equal query sets share listeners; different configurations observe independently. Query changes reconnect subscribers, and the last owner releases the listeners.

SSR keeps defaultScreens without browser access. Row responsive justify/align have no first-frame match; responsive gutter uses the largest configured breakpoint without viewport information, then corrects after mount. Server and hydration first frames are deterministic; the mounted correction can change layout.

## Theme and static CSS boundaries

Row/Col have no component Tokens. The 24-column count is geometric. Fonts consume current global fontFamily/fontSize variables. Horizontal gutter combines Row negative-half margin and Col positive-half padding; vertical gutter uses row-gap. Base and responsive flex may shrink in nowrap rows through min-width: 0, overridable by native styles.

Col CSS media queries use the fixed default thresholds above. Runtime screen Token overrides affect the JavaScript observer and Row, and do not rewrite Col media queries. Keep default thresholds or provide application static CSS when consistency is required. See [Grid migration notes](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/grid-contracts.md) for changes and verification boundaries.


## Basic (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>
```

## Grid Gutter (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>
```

## Grid Offset (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>
```

## Grid Sort (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>
```

## Layout (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>
```

## Alignment (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>
```

## Order (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 Stretch (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 (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>
```

## Responsive 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 (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 (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 (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


Previewable image. The preview overlay is portaled and supports zoom / rotate /
flip / switching inside a group.

## When to use

- Show an image and let the user click it to view the larger preview.
- A set of images needs one shared preview with prev/next switching
  (`Image.PreviewGroup`).
- You need a placeholder while loading and a fallback when loading fails
  (`placeholder` / `fallback`).

## Demos

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/image/demo) (18 native demos): 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

| Property | Description | Type | Default |
|---|---|---|---|
| prefixCls | Full root prefix; follows the current prop and falls back to the current ConfigProvider namespace when removed | `string` | `apollo-image` |
| src | Image source | `string` | — |
| width / height | Size. Numbers are normalized to `px` (see Design notes) | `number \| string` | — |
| alt | Image alternative text; a nonempty value also names the trigger/dialog. Omission produces empty img alt and generic trigger/dialog names | `string` | `''` |
| fallback | Image shown when loading fails | `string` | — |
| placeholder | Placeholder content; `{ progress: true \| { percent, render } }` renders the progress layer | `VNodeChild \| { progress }` | — |
| preview | `false` disables preview; object form see below | `boolean \| PreviewConfig` | `true` |
| open | Top-level controlled open state; supports `v-model:open` | `boolean` | — |
| defaultOpen | Uncontrolled initial state; later changes do not reset it | `boolean` | `false` |
| class / style | Native root attrs. Style accepts Vue strings, objects and arrays, overrides `styles.root`, and stays on the root; use `styles.image` for the img | `string \| array \| object` / `StyleValue` | — |
| wrapperStyle | ⚠️ Deprecated, use `styles.root` | `CSSProperties` | — |
| classNames / styles | Semantic class names / styles, see "Semantic slots" | — | — |
| crossOrigin / decoding / loading / referrerPolicy / sizes / srcSet / useMap / draggable | Native attributes forwarded to `<img>` | — | — |

Progress/standalone-placeholder branches forward native attrs to the existing Progress root and merge Image root and placeholder.progress semantics, with native style last. ID/data and naming/description ARIA stay current; progress owns its role, range and busy state. Removing an explicit aria-label restores the percentage name. Root click notifies once without opening preview; img errors stay on the img. See the [native style correction](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-native-styles.md).

### Image · Slots

| Name | Description | Scope |
|---|---|---|
| imageRender | Customize thumbnail content; an empty slot suppresses the default img | One `ImageRenderInfo` object; details below |
| previewImage | Customize the preview image area | One PreviewImageInfo object |
| previewActions | Customize the preview toolbar | One PreviewActionsInfo object |
| previewCloseIcon | Customize the close icon; empty slots take priority and the button keeps its name | No arguments |

`originNode` is a real VNode carrying the original ref, load/error handling, native attributes and styles. Render it with `<component :is="originNode" />`. `src` is the current raw img src, including fallback, or undefined when absent. alt/width/height reflect current props, title comes from a string native attr, and classNames.image is the merged semantic image class. A present slot takes precedence, including an intentionally empty result; removing it restores the default img. Stable images/rich nodes retain identity within the same structure. Progress/standalone-placeholder branches do not invoke this slot.

`ImageSlots` and `ImageRenderInfo` are exported from the component and package root. The top-level function prop is removed directly without a compatibility layer or deprecation period; see the [migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-render-slot.md). Preview extensions use the distinct slots below.

### Preview slot scopes

Image and PreviewGroup support previewImage/previewActions/previewCloseIcon; Group also supports previewCount. Current slot functions run when preview content actually renders. Empty slots suppress defaults, and removing them restores defaults. Closed/SSR previews and the Progress early branch do not eagerly invoke them. Only Group owns grouped preview extensions; a child Image's imageRender remains its thumbnail slot.

| Type | Fields |
|---|---|
| PreviewImageInfo | originNode (actual img VNode), src (raw current src including fallback, possibly undefined), alt, transform, current, total |
| PreviewActionsInfo | originNode (default toolbar VNode), icons, actions, transform, image (src/alt), current, total, disabled (zoomIn/zoomOut) |
| PreviewCountInfo | originNode (default counter VNode), current, total; Group only |

The current index is zero-based, matching the Group model; add one for display. A single image uses current=0/total=1. Transform is the current six-field snapshot. Actions provides zero-argument flipX/flipY/rotateLeft/rotateRight/zoomIn/zoomOut/reset/close callbacks using the same transform and close requests as default controls; disabled reports zoom button state. Arrow keys in inputs, textarea, select and contenteditable retain native editing behavior. Escape can still request closing, and child preventDefault takes priority.

These types, PreviewActions and PreviewGroupSlots are exported from the root entrypoint. Render `<component :is="info.originNode" />` to preserve image refs/gestures or the default toolbar. See the [preview slot migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-preview-slots.md).

### Image · PreviewConfig (object form of `preview`)

| Property | Description | Type | Default |
|---|---|---|---|
| src | Large image used by the preview (defaults to `src`) | `string` | — |
| afterOpenChange | Called after the open/close motion | `(open) => void` | — |
| cover | Thumbnail cover; false hides it, null/omission uses default content; placement-only objects are supported | `VNodeChild \| { placement?: 'center' \| 'top' \| 'bottom', coverNode?: VNodeChild }` | — |
| mask | Preview mask appearance; false hides it. Object fields are blur/className/style; semantic styles.popup.mask takes priority | `boolean \| { blur?: boolean, className?: string, style?: Record<string, string \| number> }` | `true` |
| maskClosable | Close when the mask is clicked | `boolean` | `true` |
| closable | Show the close button | `boolean` | `true` |
| closeIcon | Custom close icon | `VNodeChild` | — |
| movable | Allow dragging | `boolean` | `true` |
| minScale / maxScale / scaleStep | Zoom bounds and step | `number` | `1` / `50` / `0.5` |
| zIndex | Overlay z-index | `number` | `1080` (`zIndexPopupBase + 80`) |
| getContainer | Current overlay container; falls back to ConfigProvider.getPopupContainer, then body | `() => HTMLElement` | `document.body` |
| icons | Icon slots (rotateLeft/rotateRight/zoomIn/zoomOut/close/left/right/flipX/flipY) | `PreviewIcons` | built-in icons |
| rootClassName | Additional popup root class; semantic entry is classNames.popup.root | `string` | — |
| maskClassName | Additional popup mask class; semantic entry is classNames.popup.mask | `string` | — |

Close icon priority is the current `#previewCloseIcon` → explicit `preview.closeIcon` (including null/false/0) → `preview.icons.close` → built-in icon. `closable=false` hides only the close button and skips its icon slot; Escape, maskClosable and the toolbar close action retain their behavior. Live visibility/content updates retain preview identity, editors and transforms. The button keeps an independent accessible name. See the [close-control regression](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-preview-close-remediation.md).

Image/Group read the current minScale/maxScale for zoom, wheel, double-click and non-reset transforms. Replacing/removing limits applies on the next operation; changing the configuration retains the current scale and preview identity without emitting transform. At or above the current maximum, both the zoom-in button and previewActions.disabled.zoomIn are disabled. Reset/close still return to scale 1. See the [bounds regression](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-scale-bounds-remediation.md).

scaleStep is a proportional increment: zoom-in multiplies by 1+step, zoom-out divides by it. The default 0.5 changes 1 to 1.5 and applies to wheel and double-click zoom from 1. Step/min/max must be finite positive numbers; invalid values use defaults, and max below min is normalized to min. See the consolidated [migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-contracts.md) for resources, containers, Group types and zoom behavior. Ineffective forceRender/destroyOnClose fields are removed from the type.

Loading uses actual img events and cached completion, with no extra Image constructor or validation request. Fallback removes failed srcSet/sizes so candidates cannot override it; changing src/srcSet/sizes retries the current resource. Drag accepts the primary button and releases its owning-window listeners on close, movable=false, lost button, window blur and unmount.

### Image · Events

| Name | Description |
|---|---|
| click | Original MouseEvent, after the internal preview request; supports Vue modifiers and listener arrays |
| error | Original img Event; placeholder roots do not receive image errors, and error.once belongs to the component |
| keydown | Original KeyboardEvent before built-in Enter/Space handling; preventDefault cancels that keyboard action |
| openChange | Interaction request `(nextOpen: boolean, prevOpen: boolean)`, captured before writing state |
| update:open | Boolean request for top-level `v-model:open`; prop changes do not echo events |
| transform | Complete current TransformInfo snapshot (rotate/scale/flipX/flipY/x/y); an accepted close also emits its reset, while a refused close keeps the transform |

With preview=false, native role/tabindex/aria-label survive. Ordinary preview roots own button/0. An imageRender slot or VNode cover uses a group root and adds a separate visible native preview button for nonempty image content. originNode remains a plain img that callers can place in their own native controls. Native controls, labels, editable descendants and canceled events retain their behavior without propagation modifiers. The image and noninteractive cover still open the preview; caption text remains selectable. Rich roots grow naturally while height still sizes the image; explicit root styles take priority. The button name is “Preview image: name”, using an explicit aria-label before alt. Ordinary root naming is unchanged. Progress only notifies click/keydown without opening a latent preview. Bind with `@click`, `@error` and `@keydown`; onXxx in h()/ImageProps registers Vue listeners. See the [consolidated migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-contracts.md).

The modal preview locks focus and its owning body through leave completion, including mask=false; each instance releases its own locks and returns focus to its actual trigger. Escape follows the owning window's top layer and IME protection, with native cancellation taking priority. Group arrow shortcuts require an unmodified, non-composing event outside editors. Reduced motion, theme motion=false and zero transition duration avoid the 500ms fallback; live preference and theme changes preserve preview content.

When imageRender completely replaces originNode, nonempty content retains a separate visible native preview button; empty slots add none. Closing prioritizes the saved connected focus target, with the current preview action as a fallback if the trigger was replaced.

Open state has one public Vue entrypoint. Without open, internal state applies; removing control resumes the last synchronized value. Interaction emits openChange before update:open, and the parent may decline a request. Legacy preview state fields are removed; non-state business hooks remain in preview. See the [model migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-open-model.md).

The ineffective preview.onTransform field moves directly to top-level `@transform`. Import TransformInfo from the root entrypoint. Listener arrays, replacement and `.once` follow Vue semantics; root DOM events with the same name do not enter this business event. See the [transform event migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/image-transform-event.md).

Opening moves focus into the preview. Tab/Shift+Tab cycle within it, and Escape requests closing. A controlled parent declining that request keeps focus inside. Focus returns to the original trigger after the closing animation or when the whole preview unmounts. Close and group navigation buttons have their own accessible names, including with decorative custom icons.

### Image.PreviewGroup · Props

| Property | Description | Type | Default |
|---|---|---|---|
| items | Preferred image list; native image attributes plus src/width/height/fallback and optional business metadata | `Array<string \| PreviewGroupItem>` | — |
| preview | Preview behavior; excludes Image-specific src/cover, which belong to items/child Images | `boolean \| GroupPreviewConfig` | `true` |
| open | Top-level controlled open state; supports `v-model:open` | `boolean` | — |
| defaultOpen | Uncontrolled initial state; later changes do not reset it | `boolean` | `false` |
| current | Controlled current index | `number` | — |
| defaultCurrent | Uncontrolled initial index | `number` | `0` |
| previewPrefixCls | Full preview prefix; current override first, then the current Provider-derived value | `string` | `${prefixCls}-preview` |
| classNames / styles | Actual group root and shared popup semantics; child Image semantics belong to the child/Provider | Corresponding PreviewGroupSemanticType fields | — |

Removing current control resumes the last synchronized index; shrinking an uncontrolled list normalizes it into range. Empty lists mount no blank dialog. Disabled/empty groups leave no inert preview button semantics on children. Both items and registered data carry dimensions/fallback and forward only native image attributes to img.

### Image.PreviewGroup · Slots & Events

| Name | Description |
|---|---|
| default | Child `Image`s (collected in registration order when `items` is omitted) |
| previewImage / previewActions | Same native preview slots as Image |
| previewCloseIcon | Same no-argument close icon slot as Image; only Group owns grouped content |
| previewCount | Native counter slot receiving one PreviewCountInfo object; current is zero-based |
| openChange / update:open | Same open requests/model notifications as Image; supports `v-model:open` |
| change | Index request `(current: number, prevCurrent: number)` |
| update:current | Numeric model request after change; supports `v-model:current` |
| transform | Same transform snapshot as Image; child Images do not duplicate group notifications |

### Semantic slots

Image consumes static semantic objects from `ConfigProvider.components.image.classNames/styles`; both Image and PreviewGroup consume their popup group for the shared preview. Field/image/map replacement, late addition and removal read current values while retaining stable images, editors and open previews. See the [ordinary image report](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-provider-remediation.md) and [popup provider report](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-popup-provider-remediation.md).

Slots of `classNames` / `styles` (`placeholder` and `popup` are **nested groups**):

```
root / image / cover
placeholder.progress: root / content / rail / indicator
popup: root / mask / body / footer / actions / close
```

Provider/local classes concatenate through the nested schema before existing preview class aliases are added. Popup style fields merge shallowly: a local popup.root replaces the Provider's whole root style object, while other fields remain. Native class/style stay on the actual Image/Group root and are not copied to the popup. Native Image root style still overrides styles.root. The shared merge rules and static configuration shape are unchanged.

Group navigation icons read the current ConfigProvider.direction, resolving defaults and custom icons before mirroring for ltr/rtl. A one-sided custom icon retains the other default, and explicit null stays empty. Replacing/removing icons updates the open preview while retaining image, transform and editor state. Previous/Next still request adjacent indices and keep their names. See the [direction regression](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-provider-direction-remediation.md).

### Static properties / named exports

| Name | Description |
|---|---|
| `Image.PreviewGroup` | Preview group. Also exported as `ImagePreviewGroup` |
| `genImageStyle(prefixCls?)` | Emits the full CSS of this component (for custom prefixes) |
| `genImageTokenDecls()` | Component variable declaration block (mirrors antd's `-css-var` block) |
| `prepareImageComponentToken(seed)` | Component token derivation (type `ImageComponentToken`) |

### Type exports

`ImageProps`, `PreviewConfig`, `PreviewGroupProps`, `GroupPreviewConfig`, `PreviewIcons`,
`PlaceholderType`, `ImageProgressConfig`, `ImageStatus`, `CoverPlacement`, `MaskType`,
`TransformInfo`, `ImageSemanticType`, `PreviewGroupSemanticType`, `PreviewGroupItem`, `ProgressClassNames`, `ProgressStyles`. Image.PreviewGroup has the same complete declaration type as the named ImagePreviewGroup export.

## Theme (Component Token)

7 tokens (CSS variables `--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 by default, mapped to `--apollo-image-preview-switch-size`) controls the actual group switch width and height.

Override all seven through `ConfigProvider.theme.components.Image`. Thumbnail, Progress and body-mounted preview read current alias/component variables from the same Vue context, including an outer ThemeProvider, nested inheritance, dark/compact algorithms and replacement/removal. Static CSS owns unconfigured defaults. Native Image style and popup semantic styles can override variables. Stacking priority is preview.zIndex, styles.popup.root.zIndex, parent overlay context, then the component variable. See the actual component-token demo and [shared evidence](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-contract-audit.md).

The default group counter uses a `colorBgSpotlight` background and inherits the footer operation color, including over a light page or with the mask disabled. This background applies only to the default counter node (also available as `previewCount.originNode`); custom counter slots keep their own styling. See the [contrast regression](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-counter-contrast-remediation.md).

## Design notes

### Numeric `width` / `height` are normalized to `px`

Vue's `style` does **not** append `px` to numbers (that is React's behavior) — a bare
number is silently dropped. The component therefore routes every size through
`toCssSize()`: the root and `<img>` `style`, and the `Progress` width/height.
Missing this does not throw — the `<img>` falls back to the CSS `height:auto`, keeps the
intrinsic ratio and gets the wrong height: it **looks fine but is the wrong size**, and
only the L6 pixel comparison can catch it.

### The variable declaration block covers two roots

Static defaults cover both `.apollo-image` and `.apollo-image-preview`. Configured themes write current CSS variables on each actual root. Vue provide/inject preserves source context across Teleport, so the preview does not depend on source DOM ancestry. No component stylesheet or global theme patch is generated at runtime.

### The preview overlay is portaled

The SSR-visible part of `Image` is the root `div` + `<img>` + placeholder + cover; the
preview overlay is mounted to `body` through `@apollo-design/portal` (`getContainer` can
change that), so it is **absent from the SSR output**. With `preview=false` the overlay
component is not mounted at all.

### Style imports

```ts
import '@apollo-design/theme/tokens.css'; // theme variables, required first
import '@apollo-design/ui/image/style.css';    // on demand
// or
import '@apollo-design/ui/style.css';          // all-in-one
```

The default published CSS uses the apollo namespace. `ConfigProvider.prefixCls="my-app"` produces `my-app-image` and `my-app-image-preview`; generate and load matching CSS with `genImageStyle('my-app')` during the application build. Image.prefixCls and Group.previewPrefixCls accept full prefixes. Dynamic updates change DOM names and require the corresponding CSS to be preloaded; the component generates no runtime styles. Open previews and stable rich nodes retain state; see the [prefix evidence](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/audit/2026-10-25-image-prefix-remediation.md). The broader D04 strategy remains separate.

## FAQ

**Why is the preview overlay `z-index` 1080?**

`zIndexPopup = zIndexPopupBase(1000) + 80`, identical to antd; override it with
`preview.zIndex`.

**Can `items` and the default slot be used together in `Image.PreviewGroup`?**

`items` wins. When it is omitted, child `Image`s are collected in registration order
(registration returns an auto-incrementing id).

**Is the overlay re-created when switching inside a group?**

No. A group mounts exactly **one** `Preview` and updates `src` / `mousePosition` on switch.

Group ownership follows Vue registration: nested groups stay isolated and Teleport retains the owning group. Explicit items take priority; removing items restores registered children. If the opener is removed, closing returns focus to an available action in the same group. Uncontrolled selection is normalized after deletion; data changes do not echo change/update:current.


## Semantic styles (style-class)

Use `classNames` and `styles` to customize the root, image and preview cover. The first example retains its custom hover cover and preview behavior.

The native `class` / `style` example cycles a dynamic `StyleValue`: string, mixed array, object and removal. Native style controls only the actual outer root and overrides semantic root styles; the img's independent `styles.image` stays intact. Removal restores semantic root values while the rich image, input draft and focus remain.

The progress branch also retains native root id, data, accessible name/description and style while the component owns the progressbar role and values. The local data URI avoids external image requests.

An independent ConfigProvider control replaces the entire `components` map: empty, a fresh Image configuration A, a fresh configuration B, then removal. The factory produces `ImageSemanticType` data objects. Root, img and cover classes and extra CSS variables update with the configuration; placeholder.progress classes stay current too. Under the existing shallow merge, the local progress style group replaces the Provider group, so Provider-only variables inside that group are not retained. Local semantic styles and native root style keep their priority; the existing style cycle and input draft remain independent.

### 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 usage (click to preview).

### 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)

Override all seven Image tokens through a local ConfigProvider. The body-mounted preview retains its source theme. Cycle custom light, compact dark and removed themes while open; icon size, group switch size, stacking and progress duration follow the current values while the preview and editor remain mounted.

### 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)

Control preview with top-level `v-model:open`. The parent button updates the model directly; image activation and preview closing update it through the component. `@open-change(next, prev)` shows the component's requested transition. Direct parent assignments do not emit this event.

The other button mounts an uncontrolled image with top-level `defaultOpen`, opening its preview initially. The component manages subsequent state. Both state APIs live outside the `preview` configuration object.

### 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` for the cover position.

### 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)

Receive the current rotation, scale, flips and translation through top-level `@transform="info => ..."`. Its `TransformInfo` payload is a snapshot, and `@transform.once` follows standard Vue event semantics. Image and PreviewGroup share this event; grouped child Images do not duplicate it. Closing resets the transform and emits that snapshot. A parent declining a close request keeps the transform.

The ineffective `preview.onTransform` field is removed directly in favor of this event, without a compatibility channel. Import `TransformInfo` from `@apollo-design/ui`.

Cycle the default, narrow and higher-minimum bounds while open. Changing bounds keeps the preview and emits no transform by itself; the next zoom, gesture or other non-reset transform reads the current limits. At or above the maximum, both the zoom-in button and slot disabled.zoomIn are disabled. Removing the limits restores their defaults; reset/close still return to scale 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)

Show `fallback` image when load failed.

### 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>
```

## Provider preview styles (popup-provider)

Image and PreviewGroup both consume `ConfigProvider.components.image.classNames.popup/styles.popup`. Cycle the entire components map through empty, A, B and removal. A toolbar button updates it while the preview and current transform stay in place.

Classes concatenate in Provider/local order. Popup style fields merge shallowly: local styles.popup.root replaces the Provider's whole root style object, while other fields remain. Native class/style stay on the actual Image/Group root. Configurations are static data objects supporting field/object replacement, late addition and removal.

The direction button switches the Provider between ltr/rtl. Group navigation icons mirror using the current direction, with defaults retained for unspecified icons. Previous/Next continue to request adjacent indices and keep their accessible names.

### 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)

Extend the image with the native `#imageRender="info"` template. Render `<component :is="info.originNode" />` to preserve the real img, current source, dimensions, semantic class and loading behavior while adding the current caption.

The controls update caption, alt, dimensions and a local data URI source. With the same structure, the image node, input draft and focus remain. An intentionally empty slot suppresses the default image; removing the slot restores the current default img. The first part disables preview to inspect native component events. The second keeps preview enabled: a separate visible native preview button shares the group with the plain origin img, editors and save buttons. Native controls need no propagation modifiers. The image and noninteractive cover can open the preview, cover buttons retain their own clicks, and caption text remains selectable.

The root is a named, focusable `role="group"`. Standard Vue `@click`, `@keydown`, `@error` and their `.once` listeners show counts and original event types. The input stops click and keyboard propagation. With preview disabled, clicks and keys do not emit `update:open`, so its counter stays at zero.

The top-level `imageRender` function declaration is replaced directly by this native slot without a function-prop compatibility channel. Preview configuration fields with the same name are outside this migration.

The third part replaces originNode completely and retains a separate visible native preview button for keyboard access. Empty slots do not add it. The native cover button uses theme text/background colors, and captions use secondary text for readable contrast.

### 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)

Use native `#previewCloseIcon` on Image or PreviewGroup to customize the close icon. A present slot takes priority over `preview.closeIcon` and `preview.icons.close`, including an intentionally empty result. Removing it restores configured or default content. The button retains its own accessible name.

Cycle through a slot icon, an empty slot, VNode configuration, a hidden button and the default icon. `preview.closable=false` hides only the close button and does not evaluate the icon slot; Escape, mask and toolbar close actions keep their own behavior. Live changes retain the image, editable note and transform.

### 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)

Image nested in another container (preview still portaled).

### 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)

Use `placeholder.progress` to show a generating progress.

### 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)

Put multiple images in `Image.PreviewGroup`.

The default counter uses the theme's `colorBgSpotlight` background to retain text contrast, including when the mask is disabled.

### 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)

Extend preview images, toolbars and counters through native `#previewImage`, `#previewActions` and `#previewCount`. Each slot receives one info object. Render its original VNode with `<component :is="info.originNode" />` to preserve image gestures or the default toolbar.

The editable caption and group state survive updates. Typed actions.reset/zoomIn operate the transform. The current index is zero-based; add one for display. Empty slots suppress defaults, while removing a slot restores them. Legacy preview renderer fields and the toolbarRender alias are removed directly without a compatibility channel.

### 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)

Use top-level `v-model:open` and `v-model:current` to synchronize preview state and the current image index. Parent controls open, close or select the next image directly. Closing or switching inside the preview updates the models and emits `@open-change(next, prev)` or `@change(next, prev)`. The example displays both current models and event transitions; direct parent assignments do not emit component change events.

State lives outside the `preview` configuration, without `visible` or state callbacks inside the configuration object.

### 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)

Keep the original `width`/`height` in preview (`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)

Switch mask blur/className/style or hide it, with live scaleStep and getContainer. The toolbar updates the open preview without resetting transforms. An explicit container overrides the Provider; removing it restores the default.

### 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)

Use `preview.src` for the large preview image.

### 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

A basic widget for getting user input. Includes `Input`, `TextArea`,
`Input.Password`, `Input.Group`, `Input.Search`, and `Input.OTP`.

## Examples


## API · Input

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| value | Controlled value (`v-model:value`) | string | - |
| defaultValue | Initial value | string | - |
| size | Size | `large` \| `middle` \| `small` | - |
| disabled / readOnly | Disabled / read-only | boolean | false |
| variant | Variant | `outlined` \| `filled` \| `borderless` \| `underlined` | `outlined` |
| status | Validation status | `error` \| `warning` | - |
| prefix / suffix | Affix content; present prefix/suffix slots win, including empty slots | VNodeChild / Component | - |
| allowClear | Clear button | boolean \| `{ clearIcon, disabled }` | false |
| showCount | Show character count | boolean \| `{ formatter }` | false |
| count | Counting strategy / exceed formatter | object | - |
| maxLength | Native maxLength | number | - |
| htmlSize | Native size | number | - |
| type | Native input type | string | text |
| placeholder / autoComplete | Native placeholder / autocomplete | string | - |
| autoFocus / hidden | Autofocus / hide the logical root | boolean | false |
| prefixCls | Input class prefix | string | Provider input prefix |
| ~~clearIcon~~ | **Deprecated** use allowClear.clearIcon; absent object icons still fall back to this field and Provider | VNodeChild / Component | - |
| classNames / styles | Semantic customization | object \| function | - |
| ~~bordered~~ | **Deprecated** use `variant` | boolean | true |
| ~~addonBefore / addonAfter~~ | **Deprecated** use `Space.Compact` | VNodeChild | - |

### Events

`update:value(value: string)` and `change(event: Event)` commit ordinary edits. The event targets the actual editor and its value includes count normalization. IME retains the native draft, commits model/change once on compositionend, and deduplicates the following input. Native `input` also reports composition input.

`press-enter(event: KeyboardEvent)` is suppressed during composition. Clear writes the empty editor/model, emits `clear(event: MouseEvent)`, then dispatches a native input on the actual editor whose processing emits change. Listen to clear instead of testing change.type for click.

Native focus, blur, keydown, keyup, mousedown, compositionstart/compositionend listeners reach the editor. Existing composition-start/composition-end listener names remain available. Semantic and native events support listener arrays and Vue .once.

### Ref

`focus(option)` (with `cursor: 'start' \| 'end' \| 'all'`), `blur()`,
`setSelectionRange()`, `select()`, `input`, `nativeElement`. input is the actual editor. nativeElement is the logical group/affix/input root that owns root class/style. Dynamic affixes, clear and count retain the editor, focus and selection.

## API · TextArea

Shares value/defaultValue, size, disabled/readOnly, variant/status, allowClear/clearIcon, count/showCount, maxLength, placeholder, autoComplete, hidden and semantic events with Input. TextArea has no prefix/suffix/addon, htmlSize or type API. Native textarea attrs, including name, id, aria-* and autofocus, reach the editor.

Adds autoSize (`true` or `{ minRows, maxRows }`), rows and resize({width,height}). Resize reports the editor border box for autoSize, native dragging and caller size changes, deduplicates equal sizes and cleans up observers/document listeners on unmount.

Class regions are root, textarea, clear, count, affixWrapper and variant; style regions are root, textarea, clear and count. Ref: focus, blur, resizableTextArea.textArea and the logical nativeElement.

## API · Input.Password

action is click (default) or hover. Hover toggles on entering the button boundary; descendant mouseover does not toggle again. The native button also supports keyboard activation.

visibilityToggle defaults to true, or accepts false / {visible,onVisibleChange,tabIndex,action}. visible controls visibility; top-level action wins. Use `#icon="{ visible }"` for icon content and classNames.icon for the button. Prefix/suffix slots match Input; the suffix slot replaces user suffix content while visibilityToggle owns the toggle button.

Password inherits effective Input fields and adds inputPrefixCls; prefixCls belongs to Password. Visibility owns password/text, so the ineffective type field is removed. iconRender migrates directly to the icon scoped slot. See docs/migrations/input-contracts.md in the repository.

## API · Input.Search

Adds to Input:

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| enterButton | `false` icon / `true` primary / text / custom node | boolean \| string \| VNodeChild \| Component | false |
| searchIcon | Custom search icon | VNodeChild \| Component | `<SearchOutlined />` |
| loading | Blocks Enter and button search, including custom buttons | boolean | false |
| onSearch | `(value, event, { source })`; `source='clear'` when cleared | function | - |
| inputPrefixCls | Prefix for the inner Input | string | - |
| addonAfter | Node appended after the button | VNodeChild \| Component | - |

Semantic regions: `{ root, input, prefix, suffix, clear, count, button }`. Native custom buttons retain disabled; custom components must forward attrs/state. Content VNodes and arrays are rendered inside the owned button.

Search keeps Input type, defaults to search, and forwards prefix/suffix slots. search(value,event,{source}) supports .once; source is input or clear. nativeElement is the outer Compact root, while input is the editor. Native class/style/hidden and data attrs target the outer root; other native fields target the editor.

## API · Input.OTP

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| length | Positive integer cell count, at least 1; nonfinite values fall back to 6 | number | 6 |
| value / defaultValue | Controlled / initial value (`v-model:value`) | string | - |
| onChange | Fires when all cells are filled and the value changed | `(value: string) => void` | - |
| onInput | Fires on every cell change (array) | `(value: string[]) => void` | - |
| formatter | Format the value (e.g. uppercase) | `(value: string) => string` | - |
| separator | Static content including zero; use `#separator="{ index }"` for dynamic content | VNodeChild | - |
| mask | Mask (`true` = •, or a single character) | boolean \| string | false |
| type / inputMode / autoComplete | Passed to each native input | string | - |
| autoFocus | Focus the first cell | boolean | false |
| classNames / styles | Semantic slots `{ root, input, separator }` | object \| function | - |

Every settled edit updates v-model:value, including partial values. input emits cells; change emits only a changed complete value. Rejected controlled proposals retain the owner value. Formatting happens before the Unicode code-point clamp. Paste focuses the resulting cell; horizontal arrows follow RTL direction.

Ref: focus, blur, nativeElement (the OTP container).

## API · Input.Group

Group retains prefixCls, size, compact and the default slot. compact changes group layout; size supplies a child default. It has no value model, semantic events or editor Ref. Group is deprecated; use Space.Compact.

## Theme, sizing and styles

Default fonts, nonnegative padding and focus shadows consume the current theme. `theme.components.Input` supports the existing 19 fields: `lineWidthFocus`, `paddingBlock/SM/LG`, `paddingInline/SM/LG`, `addonBg`, `activeBorderColor`, `hoverBorderColor`, `activeShadow`, `errorActiveShadow`, `warningActiveShadow`, `hoverBg`, `activeBg`, `inputFontSize/SM/LG`, and `inputAffixPadding`. Lengths accept numbers (px) or CSS length strings, including zero. Removing an override restores the current theme default. `inputAffixPadding` controls affix spacing. The public `prepareInputComponentToken` still prepares the supplied numeric snapshot.

Size priority is explicit component `size` → nearest `Space.Compact` / `Input.Group` → `ConfigProvider.componentSize`. Group supplies a default; an explicit child size wins. Input keeps its natural line box and preserves explicit fonts, line heights and padding. Default small/middle/large heights are 24/32/40px; compact heights are 22/28/35px. A natural small line box can exceed `controlHeightSM`. Different control types do not promise identical outer heights. Search's default button stretches naturally without a Search-owned minimum height; caller `height` / `min-height` follows their CSS. TextArea retains rows, its existing minimum height and autoSize constraints. autoSize compares actual sizing inputs after theme, size, control/ancestor class or style, width and completed layout transitions change. Unrelated styles skip measurement; disabling or unmounting cleans up observation and events.

Semantic classNames/styles callbacks see current complete props and effective size, disabled, variant and status. Component theme data is merged before explicit semantic styles and native `style`. Provider `components.input/textArea/inputPassword.style` targets the logical component root; `styles.input` / `styles.textarea` targets the native control. Search and OTP root styles target their container; use `styles.input` for their actual input nodes. Existing stylesheet `--apollo-input-*` overrides remain effective. Explicit component theme fields are supplied as inline variables on the logical root.

An explicit empty `ThemeProvider :theme="{}"` (or `createThemeContext({})`) remains a default theme source and resets defaults within an outer CSS theme scope. Without an active source, Input preserves CSS-only variable inheritance. A ConfigProvider without a theme continues to consume the nearest active source and does not overwrite a CSS-only scope with default data.

## Notes

- No trimming happens during IME composition; one `change` is emitted on `compositionend`.
- Clear and visibility toggles use keyboard accessible native buttons with current locale names. Explicit null/false/zero icons stop fallback; undefined continues fallback. Empty/disabled/read-only clear buttons cannot activate.
- The clear button emits a `change` whose `target.value` is always an empty string.
- `Input.Group` is deprecated — use `Space.Compact`.


## Basic (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>
```

## Sizes (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>
```

## Prefix & suffix (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>
```

## allowClear (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>
```

## showCount (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)

`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 (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>
```

## Variants & status (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 (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 (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 (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 (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 (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 (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>
```

## Compact Group (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 (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 Loading (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 (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 (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>
```

## Component 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)

`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 (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 (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)

用 `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

Enter a number within certain range with the mouse or keyboard.

## Examples


## API

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| value | Current value (`v-model:value`); `null` means empty | number \| string \| null | - |
| defaultValue | Initial value | number \| string | - |
| min | Min value | number \| string | - |
| max | Max value | number \| string | - |
| step | Step; decimals supported | number \| string | `1` |
| precision | Precision; `formatter` wins when both set | number | - |
| formatter | Display formatter | (value, info: { userTyping, input }) => string | - |
| parser | Parse back from `formatter` | `(displayValue: string \| undefined) => string \| number` | - |
| disabled | Disabled | boolean | `false` |
| readOnly | Read-only | boolean | `false` |
| keyboard | Enable keyboard behavior | boolean | `true` |
| controls | Show step buttons / custom icons | boolean \| { upIcon, downIcon } | `true` |
| mode | Input or spinner | `'input'` \| `'spinner'` | `'input'` |
| stringMode | String value mode for high precision | boolean | `false` |
| changeOnBlur | Trigger `change` on blur to clamp value | boolean | `true` |
| changeOnWheel | Step with mouse wheel when focused | boolean | `false` |
| decimalSeparator | Decimal separator | string | - |
| placeholder | Placeholder | string | - |
| prefix | Prefix node | VNodeChild | - |
| suffix | Suffix node | VNodeChild | - |
| size | Size | `large` \| `medium` \| `small` | - |
| status | Validation status | `'error'` \| `'warning'` | - |
| variant | Variant | `outlined` \| `borderless` \| `filled` \| `underlined` | `outlined` |
| autoFocus | Auto focus | boolean | `false` |
| classNames / styles | Semantic customization (root/prefix/suffix/input/actions) | - | - |
| ~~bordered~~ | **Deprecated** use `variant` | boolean | `true` |
| ~~addonBefore / addonAfter~~ | **Deprecated** use `Space.Compact` | VNodeChild | - |

### Slots

| Name | Description | Scope |
| --- | --- | --- |
| prefix | Rich prefix content; takes precedence over the `prefix` prop | None |
| suffix | Rich suffix content; takes precedence over `suffix`, retaining form feedback | None |

Slots are read during rendering and support conditional insertion/removal and reactive content. An explicitly empty slot suppresses the prop. Without a slot, content props still apply. The native input, number formatting, stepping and v-model behavior stay intact.

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| change | Value change (emitted together with `update:value`) | (value: number \| string \| null) |
| press-enter | Enter key pressed | (e: KeyboardEvent) |
| step | Step via button / keyboard / wheel | (value: number \| string, info: { offset, type, emitter }) |

`change`, `step` and `pressEnter` are declared Vue events, supporting template listeners and `.once`. `@change` and `onChange` register the same listener, receiving a number, a string in stringMode, or `null`. The wrapper forwards each event once; native DOM `change` does not reach the semantic listener. Enter during IME composition does not flush or emit `press-enter`. Native `@keydown.prevent` cancels that internal keyboard action.

### Controlled values and native attributes

When `value !== undefined`, user changes propose updates. Rejected proposals do not become local state when control is released. Setting `value` to `undefined` retains the last value received from the parent. `defaultValue` only initializes the value; explicit `null` stays empty.

Native `class`, `style` and mouse listeners target the container. `id`, `name`, `tabindex`, label/ARIA attributes, focus/blur and keyboard listeners target the input. The component owns its numeric state, spinbutton role and numeric ARIA attributes. `input` collects display text internally; use `change` / `update:value` to observe value changes.

ConfigProvider `components.inputNumber` accepts `InputNumberConfig`: `className`, flat `style`, `classNames`, `styles` and `variant`. Root styles merge in this order: Provider semantic styles, Provider flat style, component semantic styles, native `style`. Later values take precedence. Semantic callbacks receive the current resolved `size`, `disabled`, `controls` and `variant`.

### Component tokens

Configure `theme.components.InputNumber`. Dimensions accept nonnegative numbers (converted to px) or CSS lengths. Current and nested themes update reactively; removing overrides restores the current defaults. Native CSS variables in `style` take precedence.

| Token | Description |
| --- | --- |
| controlWidth | Input width; default `90px` |
| handleWidth / handleFontSize | Step area width and icon size |
| handleVisible | In input mode: `'auto'` shows on hover/focus; `true` always shows; `false` hides |
| handleBg / handleActiveBg / filledHandleBg | Step, pressed and filled backgrounds |
| handleHoverColor / handleBorderColor | Step hover and border colors |
| paddingBlock / paddingBlockSM / paddingBlockLG | Vertical padding for each size |
| paddingInline / paddingInlineSM / paddingInlineLG | Horizontal padding for each size |
| inputFontSize / inputFontSizeSM / inputFontSizeLG | Input font size for each size |
| inputAffixPadding | Prefix/suffix spacing |
| handleOpacity / handleVisibleWidth | Idle opacity and visible width, derived from `handleVisible` by default |

### Ref

| Name | Description |
| --- | --- |
| focus(option) | Focus; `option.cursor` is `'start'` \| `'end'` \| `'all'` |
| blur() | Blur |
| nativeElement | Root DOM element |


## Basic (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>
```

## Sizes (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)

点击按钮切换可用状态。

### 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>
```

## High precision (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>
```

## Format (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)

使用 `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>
```

## Variants (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 (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 (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>
```

## Prefix & suffix (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)

使用 `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>
```

## Semantic styles (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 (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)

`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 (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-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 (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>
```

## Component 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-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 (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


Compose page structure with Layout, LayoutHeader, LayoutFooter, LayoutContent and LayoutSider. Layout.Header / Footer / Content / Sider remain available.

## Examples

All eleven paired demos use real Apollo components: basic, top, side, top-side, top-side-2, fixed, fixed-sider, custom-trigger, responsive, component-token and collapsible-overlay.

## Layout and structural regions

| Prop | Meaning | Type | Default |
| --- | --- | --- | --- |
| prefixCls | Complete DOM class prefix | string | Provider prefix + -layout |
| hasSider | Explicit boolean wins; otherwise current Sider nodes, arrays/Fragments and registered Siders are detected | boolean | Automatic |

Header/Footer/Content accept prefixCls only. A local prefix is used as-is. Tags are div/header/footer/main/aside. Every default slot accepts complete Vue content, including arrays, Fragments and zero, and is read during render. Nested Layout instances own independent Sider registrations. For an opaque component wrapper during SSR, supply hasSider explicitly.

## LayoutSider

| Prop | Meaning | Type | Default |
| --- | --- | --- | --- |
| collapsible | Show an owned toggle | boolean | false |
| collapsed | Controlled state; supports v-model:collapsed | boolean | Uncontrolled |
| defaultCollapsed | Uncontrolled initialization only | boolean | false |
| width | Expanded width; numbers/numeric strings use px, other CSS lengths remain intact | number or string | 200 |
| collapsedWidth | Collapsed width; zero uses the side toggle | number or string | 80 |
| reverseArrow | Reverse icon and zero-width toggle placement | boolean | false |
| trigger | Content of the owned button; null hides it unless a trigger slot exists | VNodeChild | Default icon |
| zeroWidthTriggerStyle | Native zero-width button style | CSSProperties | — |
| breakpoint | Responsive breakpoint subscription | xs/sm/md/lg/xl/xxl/xxxl | — |
| theme | Sidebar and toggle appearance | light or dark | dark |
| prefixCls | Complete DOM prefix | string | Provider prefix + -layout-sider |
| classNames | root/body classes; object or function receiving current { props } | SiderSemanticClassNames | — |
| styles | root/body styles; object or function receiving current { props } | SiderSemanticStyles | — |

Controlled requests preserve the current state until accepted by the parent. Releasing control retains the last accepted state. Later defaultCollapsed changes do not reset uncontrolled state. Collapsing retains content instances and editor drafts.

| Vue event | Payload |
| --- | --- |
| update:collapsed | boolean |
| collapse | (collapsed: boolean, type: clickTrigger or responsive) |
| breakpoint | broken: boolean |

JavaScript onCollapse/onBreakpoint listeners remain supported and update immediately. Business listeners are consumed as component events; other native listeners target the aside root.

Media listeners attach on mount. SSR never subscribes or emits business events. Enabling a breakpoint immediately reports its current match and requests responsive collapse when necessary. Replacing/removing a breakpoint cleans its listener; removal clears below while retaining collapsed state and emits no synthetic event. Unmount cleans all listeners. Maximum widths are 479.98 / 575.98 / 767.98 / 991.98 / 1199.98 / 1599.98 / 1839.98px.

## Slots, keyboard and refs

Sider #trigger takes precedence whenever present, including an intentionally empty result. Removing it restores trigger data/default content. Trigger data and the slot supply contents of the owned native button. Use text/icons; put independent interactive controls outside and set trigger=null to avoid nested buttons.

Owned toggles support Tab, Enter and Space, use type=button and expose an accessible name, expanded state and body association. A zero-width body is inert/aria-hidden while its instances remain mounted. Collapsing a focused body to zero moves focus to the owned toggle; external focus is retained. External controls own their labels, state and focus.

CSS-variable/expression collapsedWidth values use measured geometry to identify zero width and restore body interaction when nonzero. Toggle corners, borders and placement follow the current direction and reverseArrow together.

All five refs expose only nativeElement: HTMLElement or null. Menu reads the current Sider collapsed context; an explicit Menu inlineCollapsed value takes precedence.

## Attrs, Provider and theme

Native class/style, data/ARIA and listeners target each root. Style supports Vue objects, strings and arrays. Layout priority is current theme data → components.layout.style → native style. components.layout.className applies to Layout/Sider; its style configures Layout itself. Header/Footer/Content use their own attrs. Sider priority is theme data → styles.root → native style → width/collapsedWidth geometry; styles.body configures the content region.

All existing nineteen fields consume current theme.components.Layout with ConfigProvider, ThemeProvider without global injection, nested scopes and SSR. Finite nonnegative numeric lengths include zero and use px; valid CSS strings remain intact. Replacing/removing configuration restores current defaults.

Fields: bodyBg; headerBg/headerColor/headerHeight/headerPadding; footerBg/footerPadding; siderBg; triggerBg/triggerColor/triggerHeight; zeroTriggerWidth/zeroTriggerHeight; lightSiderBg/lightTriggerBg/lightTriggerColor. Deprecated colorBgBody/colorBgHeader/colorBgTrigger remain effective background fallbacks; modern fields win.

The default dark-blue Header uses colorTextLightSolid text. Dark/light sidebar text uses colorTextLightSolid/colorText. Existing native and stylesheet --apollo-layout-* variables override theme data. Internal -source-* variables carry existing field data and are not new component tokens or public API. Independent structural regions and Sider retain complete static defaults.

Family descendants in the same theme inherit native Alias overrides from their parent Layout. An unconfigured ConfigProvider preserves CSS-only variables. An explicit empty ThemeProvider isolates a distant theme, including through another unconfigured ConfigProvider.

## Styles and exports

    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 use layout/style.css. Sider has its own layout-sider entry; aggregate ui/style.css is also available. Components supplied through business slots retain their own CSS imports. Custom prefixCls changes DOM names; generate matching static styles with genLayoutStyle/genSiderStyle.

Existing props/refs/semantic types remain; LayoutSlots, SiderSlots and SiderEmits describe current slots/events. Sider root-package types use LayoutSider aliases. See docs/migrations/layout-contracts.md for the native Vue corrections.


## Basic (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 (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 (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 (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 (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 (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 (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 (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 (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>
```

## Component 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 (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


General list.

List follows Apollo’s independent lifecycle and uses a typed Vue `#item` slot for item content.

## When To Use

- To display a group of homogeneous data (news, users, search results);
- When you need pagination, grid layout, or vertical media-style items.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/list/demo) (**12**, mirroring antd's user-visible demos).

| demo | Description |
|---|---|
| `basic` | Basic list (`Item.Meta` with avatar / title / description) |
| `simple` | Three sizes with header / footer / border |
| `vertical` | `itemLayout="vertical"` two-段 layout + `actions` + pagination |
| `grid` | Grid layout via `grid.column` |
| `responsive` | Responsive columns via `grid` breakpoints |
| `loadmore` | `loadMore` replaces the bottom pagination |
| `pagination` | `position: 'both'` (top + bottom) |
| `spin-debug` | The two `loading` shapes |

Additional examples cover `component-token`, `pagination-simple`, `empty` and `item-extra`.
See `Listy` for virtual lists. A List drag-reordering example remains under review.

## API

### List

| Property | Description | Type | Default |
|---|---|---|---|
| bordered | Toggles rendering of the border around the list | `boolean` | `false` |
| dataSource | Data source | `T[]` | — |
| extra | Content beside the list; moves below it on narrow screens. Also available as a slot | `VNodeChild` | — |
| grid | Grid config (`gutter` / `column` / `xs`…`xxxl`) | `ListGridType` | — |
| id | Root element id | `string` | — |
| itemLayout | Item layout | `'horizontal' \| 'vertical'` | `'horizontal'` |
| loading | Loading state. ⚠️ **with a non-empty `dataSource` the list itself renders** (the 53px placeholder only shows when the data is empty) | `boolean \| SpinProps` | `false` |
| loadMore | Load-more content (**replaces** the bottom pagination) | `VNodeChild` | — |
| pagination | Pagination config; `false` renders nothing | `PaginationConfig \| false` | `false` |
| rowKey | Row key (function or field name) | `((item: T) => string \| number) \| keyof T` | — |
| size | Size. `'large'` / `'small'` add `-lg` / `-sm`; `'default'` adds nothing | `'small' \| 'default' \| 'large'` | — |
| split | Toggles rendering of the split under each item | `boolean` | `true` |
| header | List header | `VNodeChild` | — |
| footer | List footer | `VNodeChild` | — |
| locale | Empty text override (**plain prop**) | `{ emptyText: VNodeChild }` | — |
| prefixCls | Class name prefix | | — |
| class / style | **Native root attrs** (not Props) | | — |

### List slots

| Slot | Scope | Description |
|---|---|---|
| default | — | Manually composed content; suppresses the default empty state |
| item | `{ item: T, index: number }` | Items on the current page; `T` is inferred from `dataSource`, `index` starts at 0 on each page; absent slot renders no data items |
| extra | — | Content beside the list; below it on narrow screens |
| header | — | List header |
| footer | — | List footer |
| loadMore | — | Replaces bottom pagination; top pagination remains |

The presence of `header` / `footer` / `loadMore` / `extra` slots overrides their matching content props, even when the slot is empty. Empty header/footer slots create no wrapper. Use the exact `loadMore` casing. Simple content props remain available.
`renderItem` has been removed directly; see the [List slot migration](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 }} users</template>
</List>
```


`pagination.current` and `pagination.pageSize` independently select controlled state. Uncontrolled defaults initialize when pagination is first enabled. External updates do not emit callbacks; removing control continues the last received value, without adopting rejected page requests. Shrinking data clamps uncontrolled state without reviving the old page on regrowth. Explicit `total` supports server pagination and preserves the current server result page. `align` reaches Pagination unchanged (default `end`); `position` only controls List placement.

Grid columns use the largest active configured breakpoint, falling back to `column`. The nearest List/Item context supplies child prefixes; explicit child prefixes override it, following the library's static CSS generation policy. Nested List sizes, split lines, layouts and borders remain independent. Native `dir` overrides Provider direction.

### List.Item

| Property | Description | Type |
|---|---|---|
| actions | Action area. One `<li>` each, with separators between. ⚠️ **an empty array renders nothing** | `VNodeChild[]` |
| extra | Extra content in a stable `-item-extra` wrapper in both layouts | `VNodeChild` |
| classNames | Semantic class names (`actions` / `extra`) | `{ actions?: string; extra?: string }` |
| styles | Semantic styles (same slots) | `{ actions?: CSSProperties; extra?: CSSProperties }` |
| colStyle | User-supplied inline style on the grid Col root; does not set List column counts | `CSSProperties` |

### List.Item slots

| Slot | Description |
|---|---|
| default | Item body |
| extra | Extra content in a stable semantic wrapper in both layouts |
| actions | Arrays and fragments are flattened; each nonempty top-level node becomes one action, with separators between actions |

Named slots take precedence over matching props, including empty slots. Actions skip comments and whitespace; use stable keys with `v-for`. Multiple buttons inside one wrapping element count as one action. The actions data array prop uses the same empty-content filtering and preserves VNode keys. Numeric zero remains visible.

### List.Item.Meta

| Property | Description | Type |
|---|---|---|
| avatar | Avatar | `VNodeChild` |
| title | Title (rendered as `<h4>`) | `VNodeChild` |
| description | Description | `VNodeChild` |

### List.Item.Meta slots

`#avatar`, `#title` and `#description` have no scope arguments and override matching props, even when empty. Empty avatar/title slots create no avatar wrapper/heading. When both title and description are empty there is no content wrapper. Numeric zero remains visible. Dynamic content updates on render.

### Instance (ref)

All three components expose `{ nativeElement }` (nullable). List / Meta use `HTMLDivElement`; Item uses `HTMLLIElement` outside a grid and `HTMLDivElement` in a grid.

## Theme

### Component Token (11)

| Token | Description | Default |
|---|---|---|
| `contentWidth` | Width of content | `220` |
| `itemPadding` / `itemPaddingSM` / `itemPaddingLG` | Item padding (three sizes) | `${paddingContentVertical} 0` / `${paddingContentVerticalSM} ${paddingContentHorizontal}` / `${paddingContentVerticalLG} ${paddingContentHorizontalLG}` |
| `headerBg` / `footerBg` | Header / footer background | `transparent` |
| `emptyTextPadding` | Padding of the empty text | `padding` |
| `metaMarginBottom` | Margin bottom of meta | `padding` |
| `avatarMarginRight` | Right margin of avatar | `padding` |
| `titleMarginBottom` | Margin bottom of title | `paddingSM` |
| `descriptionFontSize` | Font size of description | `fontSize` |

Configure all 11 tokens through `ConfigProvider` `theme.components.List`, including updates, removal and restoration. Native root CSS variables can override them: `--apollo-list-item-padding`, `--apollo-list-content-width`, …
(11 variables). Data containers inherit root values; native root styles take precedence over Provider configuration.

An explicit `itemPadding` also controls both axes of bordered default rows; without an override, their standard theme indentation remains. `loading.fullscreen` covers the viewport while content, native input state and refs stay in document flow. Use `loading.classNames.mask` / `loading.styles.mask` for the actual overlay.

Pagination content uses #paginationItemRender="{ page, type, element }", #paginationTotal="{ total, range }" and #paginationSizeChanger="info". Each pager receives its current scope, including top/bottom pagers and dynamic slots. Configuration holds data and business events; itemRender/showTotal/sizeChangerRender function entries are removed.


## Basic (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 list (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 (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)

`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 (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>
```

## Load more (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)

`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>
```

## Loading (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>
```

## Component 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>
```

## Simple Pagination (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 Layout & Extra (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>
```

## Custom Empty (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


A data-driven list with grouping, native sticky headers and optional virtualization. Item content can contain native interactive controls.

## API

`T` is the actual item type, including plain interfaces and primitive values. `K extends string | number` is the group key type.

| Prop | Description | Type | Default |
|---|---|---|---|
| items | Data; omitted means an empty list | `T[]` | `[]` |
| rowKey | Stable key algorithm or a field whose complete value is string/number; numeric and Symbol field names work | `ListyRowKey<T>` | required |
| group | Aggregate by key, ordered by first occurrence; matching items need not be contiguous | `{ key: (item: T) => K }` | — |
| sticky | Native unique Raw headers or fixed Virtual headers | `boolean` | — |
| virtual | Inherits the current ConfigProvider.virtual when omitted | `boolean` | `false` |
| height | Raw maxHeight or Virtual viewport height | `number` | — |
| prefixCls | Component class prefix | `string` | current ConfigProvider prefix |
| classNames | Semantic classes for root, item and groupHeader | `ListyClassNames` | — |
| styles | Semantic Vue CSSProperties | `ListyStyles` | — |

Direction follows the current ConfigProvider.direction. Native class/style/data attributes belong to the outer root; style accepts Vue strings, objects and arrays. The id, tabindex, role, aria-* attributes, keyboard and focus listeners belong to the actual scrolling widget: the root in Raw mode and the holder in Virtual mode. Widget identity and ARIA share one target without duplication on the outer container. The height prop controls the viewport.

### Slots

| Name | Object scope | Purpose |
|---|---|---|
| default | `{ item: T, index: number }` | Item content; index always refers to the original items array |
| groupHeader | `{ groupKey: K, items: T[], sticky: boolean, fixed: boolean }` | Shared group template; omitted means the group key itself, including 0 or an empty string |

Zero, empty content, arrays and conditional slots are supported. An enabled Raw sticky header has sticky=true/fixed=false; ordinary Virtual headers have false/false and fixed copies have false/true. Raw rows preserve their actual node, editor state and focus across replacement, reorder and regrouping with the same key. Virtual rows preserve identity while they remain in the mounted window; offscreen rows unmount normally.

### Events

| Name | Arguments | Description |
|---|---|---|
| scroll | `(event: Event)` | One owned notification with the actual native holder event |

No synthetic event is created. Native scrolling keys, IME, user preventDefault and controls inside slots retain browser behavior.

### Ref

`ListyRef<K>` exposes only `scrollTo(config?: ListyScrollToConfig<K>): void`:

- A number sets this list's scrollTop.
- `{ key, align?, offset? }` targets an item. Align is top/bottom/auto and defaults to auto. Top alignment accounts for the sticky group header.
- `{ groupKey: K, align?, offset? }` targets a group.
- `{ left?, top? }` sets this list's scroll coordinates.
- Null/undefined specifies no new target.

Raw scrolling changes only its own holder, without scrollIntoView moving ancestor containers or the page. Virtual scrolling reuses VirtualList measurement and iteration. Numeric/string keys and group/item keys have distinct internal tags; do not parse data-key values.

## Theme

Current Provider Listy configuration and both Component Tokens react to updates and withdrawal: itemPaddingBlock (paddingSM) and itemPaddingInline (padding). Both accept numbers or CSS length strings.

Virtual's initial estimate uses the current fontHeight plus twice itemPaddingBlock. Numeric and px values are used directly; other CSS units initially use current paddingSM and are corrected by existing VirtualList DOM measurement. No additional virtualization or measurement layer is introduced.

## Migration

Replace itemRender(item,index) with `#default="{ item, index }"`, and group.title(groupKey,items) with `#groupHeader="{ groupKey, items }"`. Keep group.key as the data grouping algorithm. The old template callback props have been removed.


## Basic (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 & Sticky (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)

`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 (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 (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 Content (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 Slot (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>
```

## Custom Group Header (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


A masonry (waterfall) layout: each item is placed into the currently shortest column.
Item heights are **measured**, never preset.

## When To Use

- Content heights vary, but the container should look visually "filled"
  (image walls, card feeds, product lists).
- Columns and gaps need to be controlled per breakpoint.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/masonry/demo) (6 demos, mirroring antd one by one).

| demo | Description |
|---|---|
| `basic` | Basic (4 columns, `gutter` 16) |
| `responsive` | Columns and gaps configured per breakpoint |
| `dynamic` | Add / remove items; `onLayoutChange` writes the column back into `items` |
| `fresh` | Use `fresh` when item content resizes (a `ResizeObserver` per item) |
| `image` | Items are images (heights are known only after loading) |
| `style-class` | `classNames` / `styles` in both object and function form |

## API

### Props

| Property | Description | Type | Default | Global Config |
|---|---|---|---|---|
| items | Data source. Each entry is `{ key, data, column?, height?, children? }` | `MasonryItemType<T>[]` | — | × |
| columns | Column count. The object form resolves per breakpoint (first configured one, from largest to smallest; if none matches ⇒ `columns.xs ?? 1`) | `number \| Partial<Record<Breakpoint, number>>` | `3` | × |
| gutter | Spacing. Reuses Grid's `Gutter` (number / string / breakpoint object / `[horizontal, vertical]`) | `Gutter` | `0` | × |
| fresh | Attaches a `ResizeObserver` to **each item** (for content that resizes). ⚠️ Does **not** change the DOM structure | `boolean` | `false` | × |
| onLayoutChange | Vue listener for `layoutChange`; receives **`{...item, column}`** after every current item has a measured position | `(sortInfo: MasonryLayoutItem<T>[]) => void` | — | × |
| classNames | Semantic class names (`root` / `item`); the function form is supported | `MasonrySemanticClassNames \| ((info) => …)` | — | ✅ (`masonry.classNames`) |
| styles | Semantic styles (`root` / `item`); the function form is supported | `MasonrySemanticStyles \| ((info) => …)` | — | ✅ (`masonry.styles`) |
| prefixCls | Class name prefix | `string` | from ConfigProvider, fallback `apollo-masonry` | × |
| class / style | **Native root attrs** (not Props). Caller styles override matching semantic styles and the computed container height | Vue class/style bindings | — | × |

Numbers in `gutter` use pixels; CSS strings such as `['2rem', 'calc(0.5rem + 4px)']`, `var()` and percentages retain their CSS units. Horizontal percentages use the container width. Vertical percentages use the current zero-gap masonry height, or the caller's explicit root height when provided; this stable basis prevents container-height feedback. A local hidden measurement node observes font, viewport and CSS-variable changes and is removed when both gaps become numbers or the component unmounts.

#### MasonryItemType

| Field | Description | Type | Default |
|---|---|---|---|
| key | Unique identifier (numbers are stringified internally) | `string \| number` | — |
| data | Business data; T is inferred from items and passed to #item | `T` | — |
| column | Pins the item to a column (0-based). Out-of-range values are clamped to the last column | `number` | the shortest column |
| height | Optional metadata passed to #item and layoutChange; does not set the measured layout height | `number` | — |
| children | Fallback content when #item is absent | `VNodeChild` | — |

### Events

| Name | Description | Parameters |
|---|---|---|
| layoutChange | Complete measured layout changed. Native Vue listeners, including `.once`, receive this single event; the emitter does not depend on an `onLayoutChange` prop | `(sortInfo: MasonryLayoutItem<T>[])` |

### Ref

| Name | Type | Description |
|---|---|---|
| nativeElement | `() => HTMLDivElement \| null` | Current root element; returns null after unmount |

Development API correction (`0.0.0`): `MasonryRef` now matches `MasonryExpose`. Read the root with `masonryRef.value?.nativeElement()`; the former direct-element `MasonryRef.nativeElement` annotation did not match the documented getter. There is no compatibility layer or deprecation period.

### Slots

| Name | Parameters | Description |
|---|---|---|
| item | `MasonryItemSlotProps<T>`: `{ key, data, index, column, children?, height? }` | Current item; a present slot overrides item.children, including an empty slot |

Column is the current measured column, provisionally 0 before measurement. Conditional slots, same-key data replacements (including replacing an entry in a reactive array) and semantic callbacks read current inputs. Component updates schedule measurement; use fresh to observe transitions and independent descendant resizes. T also flows into layoutChange. The itemRender prop has been removed; see the [migration guide](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/masonry-slots.md).

## Theme

### Component Token

Masonry has **no Component Token** (identical to antd: `ComponentToken` is an empty interface).
It only consumes global aliases:

| token | Used for |
|---|---|
| `motionDurationSlow` | Item fade-in (`-fade-appear`) and position transitions |
| `motionDurationFast` | Item fade-out (`-fade-leave`) |
| `motionEaseOut` | Easing of the three above |

## Design Notes

- **Layout algorithm**: items are placed in order into the column with the **smallest
  accumulated height** (ties go to the **leftmost**); the container height is the tallest
  column minus one vertical gutter. See the header of `hooks/positions.ts` for the three
  easy-to-get-wrong points.
- **SSR renders content immediately**: initial items and #item render on the server in a normal grid with natural height. After mounting, measured heights enable shortest-column positioning. The initial grid flows by rows; masonry positioning starts after measurement. Hydration retains item/input nodes and entered values.
- **Heights are measured**: `item.height` is never read; the first measurement happens
  after Vue has updated the DOM.
- **Image events trigger measurement**: native root capture listeners receive non-bubbling img load/error events and schedule a measured layout pass, including when fresh is false. Use fresh for general per-item ResizeObserver updates.
- **Zero ARIA**: both the container and the items are plain `div`s (no `role`, no
  `tabindex`); supply semantics through #item and native attrs.
- **Native attrs are forwarded**: root id/title/events and Vue string/object/array class/style are read during render. Caller styles override matching semantic root styles; updates retain the root DOM. No role/ARIA is added by default; callers can provide appropriate native attrs.


## Basic (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)

列数与间距都支持按断点配置 —— 命中规则是「从大到小取第一个已配置的断点」。

### 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 (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)

条目内容高度会变时用 `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 (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>
```

## Custom Style (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


Used to mention someone or something in an input, commonly seen in publishing, chat, or comment boxes.

## When To Use

- You need to "@ someone" or "# a tag" inside a text input and pop up candidates.
- Candidates may come from an **async** source (use `loading` + `onSearch`).

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/mentions/demo) (16 demos, covering the main antd scenarios.

| demo | Content |
|---|---|
| `basic` | Basic (`options` driven) |
| `prefix` | Multiple trigger tokens (`['@', '#']`) + `onSearch` switching data |
| `autoSize` | Height auto size |
| `autosize-textarea-debug` | The two `style.resize` values |
| `allowClear` | Clear button (default / custom icon / multiline) |
| `async` | Async candidates (`loading` + `onSearch`) |
| `placement` | Open upwards |
| `readonly` | `disabled` and `readOnly` |
| `size` | `large` / default / `small` |
| `status` | `error` / `warning` |
| `variant` | `outlined` / `filled` / `borderless` / `underlined` |
| `form` | Work with `Form` (controlled + validation) |
| `popupRender` | Customize the dropdown |
| `style-class` | `classNames` / `styles` as object or function |
| `component-token` | Component token debug (`dropdownHeight`, …) |
| `render-panel` | Static panel (debug only, do not use in production) |

## API

### Props

| Property | Description | Type | Default | Config Provider |
|---|---|---|---|---|
| value | Controlled value (with `v-model:value`) | `string` | — | × |
| defaultValue | Initial value of an uncontrolled component | `string` | — | × |
| options | Candidates (data driven) | `MentionsOptionProps[]` | — | × |
| prefix | Trigger token, array supported | `string \| string[]` | `'@'` | × |
| split | Token separator (also the default "valid search" criterion) | `string` | `' '` | × |
| filterOption | Filter candidates. `false` disables filtering | `false \| ((input, option) => boolean)` | `option.value` contains the input (case-insensitive) | × |
| validateSearch | Whether the search text is valid | `(text, split) => boolean` | Does not contain `split` | × |
| notFoundContent | Content shown when there is no candidate | `VNodeChild` | `renderEmpty('Select')` | ✅ (`mentions.notFoundContent`) |
| loading | Candidates are loading (shows a Spin and **Enter does not select**) | `boolean` | `false` | × |
| silent | Explicitly suppress selection on Enter, independently of loading; loading always suppresses selection | `boolean` | `false` | × |
| placement | Popup placement | `'top' \| 'bottom'` | `'bottom'` | × |
| getPopupContainer | Popup mount point; may return null before mounting | `() => HTMLElement \| null` | — | ✅ |
| popupClassName | Extra class name for the popup | `string` | — | × |
| size | Size | `'large' \| 'middle' \| 'small'` | From ConfigProvider | ✅ |
| disabled | Disabled | `boolean` | From `DisabledContext` | ✅ |
| readOnly | Read only; disables clear and candidate editing | `boolean` | `false` | × |
| hidden | Hide the entire component root | `boolean` | `false` | × |
| status | Validation status | `'error' \| 'warning'` | From `Form.Item` | ✅ |
| variant | Variant | `'outlined' \| 'filled' \| 'borderless' \| 'underlined'` | `'outlined'` | ✅ |
| allowClear | Clear button | `boolean \| { clearIcon?, disabled? }` | `false` | ✅ (`mentions.allowClear`) |
| rows | Rows of the textarea | `number` | `1` | × |
| autoSize | Height auto size | `boolean \| { minRows?, maxRows? }` | — | × |
| maxLength | Max length | `number` | — | × |
| placeholder | Placeholder (**also the accessible name**) | `string` | — | × |
| classNames | Semantic class names (`root` / `textarea` / `popup` / `suffix`), function supported | `MentionsSemanticClassNames \| ((info) => …)` | — | ✅ (`mentions.classNames`) |
| styles | Semantic styles (same 4 keys), function supported | `MentionsSemanticStyles \| ((info) => …)` | — | ✅ (`mentions.styles`) |
| prefixCls | Class name prefix | `string` | From ConfigProvider, fallback `apollo-mentions` | × |
| class / style | **Native root attrs** (replacing upstream `className` / `rootClassName` / `style`) | `string \| array \| object` / `StyleValue` | — | × |

Native class/style apply to the outer root in bare, allowClear and Form feedback modes. Style accepts strings, objects, mixed arrays and CSS variables, overrides matching styles.root values, and restores them when removed. id/ARIA/tabindex remain on the textarea. Current style and silent/loading updates preserve the editor node. Provider style participates in root merging; textarea, popup and suffix semantic styles reach their regions. The current ConfigProvider getPopupContainer applies unless the component specifies its own.

Controlled updates are requests: rejected input or clear requests do not become local state after control is removed. Removing value retains the last accepted value, then input updates local state. Becoming disabled/readOnly ends ordinary candidate interaction; readOnly blocks clear.

#### MentionsOptionProps

| Property | Description | Type | Default |
|---|---|---|---|
| value | Value filled back when selected | `string` | — |
| label | Display content | `VNodeChild` | — |
| disabled | Not selectable (↑/↓ skip it) | `boolean` | `false` |
| className | Class name of the option | `string` | — |
| style | Inline style of the option | `CSSProperties` | — |
| key | Only used for `data-menu-id` | `string \| number` | `value` |

### Events

| Name | Description | Arguments |
|---|---|---|
| input | Native text input | `(event: Event)` |
| focus / blur | Textarea focus changes; blur is deferred for popup focus coordination | `(event: FocusEvent)` |
| keydown / keyup | Textarea keyboard events with Vue modifiers | `(event: KeyboardEvent)` |
| clear | Sent after clicking clear, without arguments | `()` |
| update:value | Value changed (with `v-model:value`) | `(value: string)` |
| change | Value changed (**receives a string, not an event**) | `(value: string)` |
| select | A candidate is selected | `(option: MentionsOptionProps, prefix: string)` |
| search | Search text changed (entry point for async loading) | `(text: string, prefix: string)` |
| popupScroll | Popup scrolled | `(event: Event)` |
| pressEnter | Enter pressed while **not** measuring | `(e: KeyboardEvent)` |
| resize | Size changed (with `autoSize`) | `({ width, height })` |

`change`, `select` and `search` use typed emits, including Vue `.once`, listener arrays and current listener replacement. Each native input sends one value update. Native DOM change/select events do not trigger semantic events. Replace callback-prop bindings such as `:on-search="handler"` with `@search="handler"`; render-function `onSearch` remains standard Vue listener registration. See the [migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/mentions-core-events.md).

The other public events also use typed emits, including listener arrays, replacement and `.once`. Modifiers such as `@keydown.stop.prevent` operate on native events; `@press-enter` fires only outside candidate measurement. Unmount cancels pending blur callbacks; popup focus coordination does not fabricate FocusEvents. Replace `:on-press-enter`, `:on-popup-scroll` and `:on-resize` function props with `@press-enter`, `@popup-scroll` and `@resize`; see the [migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/mentions-native-events.md).

Candidate navigation uses standard `KeyboardEvent.key`: arrows skip disabled options, Enter selects once and Escape closes. Their keyup events do not repeat search or reopen the popup. While `isComposing` is true, arrows and Enter remain with the IME and public keyboard listeners still receive the original events. Provide `key` when constructing keyboard events; deprecated `which` no longer drives navigation. See the [keyboard migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/mentions-keyboard.md).

### Slots

| Name | Description | Arguments |
|---|---|---|
| default | Candidates in `Mentions.Option` form (**deprecated**, use `options`) | — |
| notFoundContent | Current empty-menu content; a present empty slot suppresses fallbacks | — |
| popupRender | Custom popup; a present slot overrides the default menu, including empty content | `{ originNode: VNode }` |

`MentionsSlots` and `MentionsPopupRenderSlotProps` are exported and attached to the component. Slots are forwarded through the current render across wrapper and engine layers. Removing the slot restores the menu; editor nodes, current value, focus and the original menu's selection behavior are preserved. The render-function prop is removed directly without a compatibility channel; see the [migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/mentions-popup-slot.md).

Empty content precedence is `#notFoundContent` (including an intentionally empty slot), the `notFoundContent` prop, `ConfigProvider.components.mentions.notFoundContent`, `renderEmpty('Select')`, then the default empty state. The slot runs only when an empty menu renders; closed/SSR, candidate and loading states do not evaluate it eagerly. A present slot also skips fallback rendering. Removing it restores current fallback data. `false` stays blank; `0`, VNodes and arrays follow Vue child normalization without extra wrapper elements.

### Expose (template ref)

| Name | Description | Type |
|---|---|---|
| focus | Focus | `() => void` |
| blur | Blur | `() => void` |
| textarea | Current native `<textarea>` | `HTMLTextAreaElement \| null` |
| nativeElement | Root element | `HTMLElement \| null` |

### Static members

| Name | Description |
|---|---|
| `Mentions.Option` | @deprecated, use `options` (also available as the named export `MentionsOption`) |
| `Mentions.getMentions(value, config?)` | **Pure function**: parse mention entities from text |
| `Mentions._InternalPanelDoNotUseOrYouWillBeFired` | Static panel (debug / docs only) |

`InstanceType<typeof Mentions>` and `MentionsRef` provide the actual methods and element types. Deprecated Mentions.Option still reads its current default slot, supporting template v-for, native class/style and string/number keys. The unused OptionProps.children field is removed; put its content in the default slot. options[].label remains VNodeChild data.

The internal static panel displays a real candidate menu when value contains a trigger prefix. The menu stays inside its host, participates in layout and is released on unmount. Ordinary Mentions gains no open prop.

### Component Token

Current global aliases and all 21 effective component fields apply to the root and teleported popup. Nested overrides, replacement and removal update existing nodes. Semantic styles and native root style keep precedence.

- Lengths (numbers become px; CSS length strings also work): lineWidthFocus, paddingBlock/SM/LG, paddingInline/SM/LG, inputFontSize/SM/LG, dropdownHeight, controlItemWidth and itemPaddingVertical.
- Strings: activeBorderColor, hoverBorderColor, activeShadow, errorActiveShadow, warningActiveShadow, hoverBg and activeBg.
- Layer: zIndexPopup; explicit styles.popup.zIndex has precedence and preserves CSS strings.

Numbers and numeric strings also define the numeric context inherited by descendant overlays. A top-level popup uses its current zIndexPopup; nested popups increment the parent layer. Explicit styles.popup.zIndex, including 0, takes precedence. CSS expressions such as `var(...)`, `calc(...)` and `auto` are preserved but do not participate in automatic numeric stacking. Descendant stacking that depends on these expressions remains deferred and unverified.

The unused addonBg field is removed without a compatibility channel. Other defaults derive from the current theme before components.Mentions overrides are applied.

## Keyboard & Accessibility

Focus **always stays in the textarea** (the candidate list is display-only,
`role="menu"` + `role="menuitem"`):

| Key | Behavior |
|---|---|
| ↑ / ↓ | Move the highlight (**skips `disabled` items**, wraps around) |
| Enter | Select the highlighted item and fill it back (no-op when `silent`) |
| Esc | Close the candidate panel |

⚠️ The accessible name of the textarea is the **consumer's** responsibility
(`placeholder` / `aria-label` / `Form.Item` label), matching antd — the component
cannot guess what the text is about.

## Design guidance

- When there are more than ~10 candidates, use `onSearch` for async filtering (see the `async` demo).
- `split` marks the end of a mention: the default space means `afc163` is one complete mention in `@afc163 hello`.
- When filling back, a `split` is inserted before the token if the preceding text lacks one, and the
  duplicated head shared with the candidate is removed.


## allowClear (allowClear)

Customize clear button.

### 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)

Load candidates asynchronously and show the current query with the native `#notFoundContent` template. Update its content, leave the slot intentionally empty, or remove it to restore the current `notFoundContent` data. The controls preserve editor focus; matching candidates still support selection and clear.

### 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)

Height 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 usage.

### 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)

Toggle component tokens to change the current menu's maximum height, minimum width and layer.

### 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)

Controlled mode, for example, to work with `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)

Change the suggestions 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)

Wrap the default menu with the native popupRender slot and its single originNode context. After typing @, toggle, update or empty the slot. Empty content suppresses the menu; removing the slot restores it. Mouse toolbar actions preserve editor focus, and the original menu retains keyboard navigation and selection.

### 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)

Customize Trigger Token by `prefix` props. Default to `@`, `Array<string>` also supported.

### 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)

Configure `disabled` and `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)

Debug usage. Do not use in your production.

### 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)

Configure size via `size` property.

### 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)

Add status to Mentions with `status`, which could be `error` or `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)

You can customize the semantic dom style of Mentions by passing objects/functions through `classNames` and `styles`. For example, set the textarea to be resizable.

### 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)

Variants of Mentions, there are four variants: `outlined` `filled` `borderless` and `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


Horizontal, vertical and inline navigation driven by `items`. See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/menu/demo).

## API

### Props

| Property | Description | Type | Default |
|---|---|---|---|
| items | The content source, including VNode data and per-item icon functions | `ItemType[]` | — |
| mode / theme | Layout and light/dark theme | `'horizontal' \| 'vertical' \| 'inline'` / `'light' \| 'dark'` | `'vertical'` / `'light'` |
| selectedKeys / defaultSelectedKeys | Controlled selection / initial selection; `v-model:selectedKeys` | `string[]` | `[]` |
| openKeys / defaultOpenKeys | Controlled opening / initial opening; `v-model:openKeys` | `string[]` | `[]` |
| activeKey | Controlled active item; withdrawal keeps the last accepted value | `string` | — |
| selectable / multiple | Selection / multiple selection | `boolean` | `true` / `false` |
| disabled | Inherits ConfigProvider when omitted | `boolean` | — |
| inlineCollapsed | Collapsed icons; falls back to Sider | `boolean` | — |
| tooltip | Collapsed-item Tooltip options; false disables it | `false \| TooltipProps` | — |
| inlineIndent | Inline indentation in px | `number` | `24` |
| triggerSubMenuAction | Popup activation; inline menus use click and keyboard | `'hover' \| 'click'` | `'hover'` |
| subMenuOpenDelay / subMenuCloseDelay | Hover delays in seconds | `number` | `0.1` / `0.1` |
| forceSubMenuRender / disabledOverflow | Preserve submenu rendering / disable horizontal overflow | `boolean` | `false` |
| getPopupContainer | Popup container; inherits the current ConfigProvider | `(node: HTMLElement) => HTMLElement \| ShadowRoot` | — |
| prefixCls / id / role / tabIndex | Current prefix and root-list attributes | `string` / `string` / `string` / `number` | — / — / `'menu'` / `0` |
| classNames / styles | `root/list/item/itemTitle/itemIcon/itemContent`, nested `popup.root` and `subMenu` | `MenuClassNames` / `MenuStyles` | — |

Native class, style (including strings and arrays), data/ARIA attributes and native listeners reach the actual root ul in every mode. `click` carries a Menu business payload. Native keyboard listeners use `@keydown`, or `onKeydown` with h(). Native root styles override Provider and semantic styles. The hidden path-registration tree receives none of these root attributes.

### Emits

| Event | Payload |
|---|---|
| update:selectedKeys / update:openKeys | `string[]` |
| click | `MenuInfo`: key, keyPath, itemData and native domEvent |
| select / deselect | `SelectInfo`, including selectedKeys; deselect only removes a multiple selection |
| openChange | Proposed `string[]` |

Vue owns these notifications, including listener arrays and `.once`. keyPath runs from the item to the root. domEvent can cancel a link's default navigation. Rejected controlled proposals do not contaminate state after control is withdrawn.

### Data and slots

Item label, extra, icon and itemIcon remain data fields. Icon functions receive RenderIconInfo. Submenu expandIcon functions and per-item click/title/hover handlers retain their data responsibility. A submenu theme also reaches descendant popups. An explicit `type: 'submenu'` supports an empty children array.

| Component | Slot | Scope / content |
|---|---|---|
| Menu | expandIcon | `{ isOpen, isSelected, isSubMenu, disabled }`; per-item expandIcon takes precedence |
| MenuItem | default / title / extra | Main content and extra content; a text title prop remains available |
| MenuItem | icon | RenderIconInfo |
| MenuSubMenu | title / icon / expandIcon | Icon slots receive RenderIconInfo |
| MenuItemGroup | title / default | Group title / children |

Slots are read during rendering. A present slot wins, including intentionally empty, text and multiple-node results. Menu does not interpret its default slot as a second menu declaration tree: items and path registration retain one data source. Existing static components use the same internal Menu context.

### Expose

`list: HTMLUListElement | null` is the current root, including horizontal Overflow. `focus(options?)` focuses the first enabled item. `findItem({ key })` finds this instance's actual item, including teleported submenus and keys containing quotes. Element references clear on unmount.

## Provider and styles

The current components.menu className/style/classNames/styles, global disabled state, direction and popup container respond to replacement and removal. theme.components.Menu supports the existing ten numeric tokens: dropdownWidth, zIndexPopup, radiusItem, itemBorderRadius, radiusSubMenuItem, subMenuItemBorderRadius, activeBarWidth, activeBarHeight, activeBarBorderWidth and itemMarginInline. The legacy radius aliases affect the corresponding radius unless its modern field is explicit. Other static CSS variables remain available for direct styling; they are not additional implemented component tokens. Current aliases and these ten tokens reach root, inline and actual popup lists. Numeric popup layers also provide descendant context. Nonnumeric CSS layer expressions retain their styles; automatic numeric descendant layering for expressions remains deferred.

## Keyboard and lifecycle

Enter or Space on an item activates its single owned native link or button, or emits one ordinary item action. A focused native control owns its browser activation. Disabled items block native navigation. Inputs and editable content keep their own keys. With multiple native actions, focus the intended control directly.

Inline lists hide after closing motion. Leaving inline mode removes them after motion; initial mounting does not animate. Pending hover timers and focus frames are released on unmount.

## Development migration

Use #expandIcon instead of the top-level expandIcon rendering prop, and #icon for static item icons. Per-item rendering functions remain. Replace onKeyDown with native onKeydown / @keydown. The unused children type field is removed; content continues to use items. Business listeners keep @click/@select/@deselect/@openChange and their programmatic onClick/onSelect/onDeselect/onOpenChange names.


## Native links and buttons (native-actions)

Arrow keys move menu focus. Enter on an item activates its single native link or button. Focused child controls retain browser activation; plain items also support Space. Actions run once and disabled links do not navigate.

### 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 (custom-style)

Adjust item height, border radius, selected background and text color through the root `--apollo-menu-*` component tokens, and set the content font weight via `styles.itemContent`.

Click a menu item to toggle its selected state.

### 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 (extra-style)

Render extra content on the right via the `extra` field of items.

### 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)

Horizontal top navigation menu.

### 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)

Horizontal navigation menu in dark theme.

### 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 menu (inline)

Vertical menu with inline submenus.

### 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 (inline-collapsed)

Click the button to collapse/expand the menu; collapsed titles use 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>
```

## With Layout.Sider (sider-current)

Collapse linkage with 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>
```

## Custom style (style-class)

Customize menu items via `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)

Set an independent theme for a submenu.

### 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)

Switch between inline and popup menu modes.

### 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 (theme)

Supports two themes: light and 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)

Show the menu title in a Tooltip when collapsed.

### 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)

Submenus appear as popups.

### 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 tokens (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


Display global feedback messages. Imperative API (`message.success(...)`), the overlay is portaled.

## When to use

- Show a short-lived result of an operation at the top of the page (success / error / warning / loading).
- Chain a "in progress → done" flow (`loading` + `then`).
- ⚠️ Prefer `message.useMessage()` and its `contextHolder`: static methods **cannot consume
  component context**. Static instances read the global services configured through `ConfigProvider.config()`.

## Demos

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/message/demo) (11 demos, covering the main antd scenarios
info / loading / other / render-panel / stack / style-class / thenable / update.

## API

### Static methods

| Method | Description | Signature |
|---|---|---|
| `message.success` / `info` / `warning` / `error` / `loading` | Open a message of that type | `(content, duration?, onClose?) => MessageType` |
| `message.open` | Open with full config | `(config: ArgsProps) => MessageType` |
| `message.destroy` | Close one (by key) or all | `(key?: string \| number) => void` |
| `message.config` | Global defaults (**merged**) | `(config: ConfigOptions) => void` |
| `message.useMessage` | Hook form | `(config?: ConfigOptions \| (() => ConfigOptions)) => [MessageInstance, () => VNode]` |
| `message._InternalPanelDoNotUseOrYouWillBeFired` | Private: single static panel (docs/debug) | component |
| `message._InternalListDoNotUseOrYouWillBeFired` | Private: static list (same) | component |

> ⚠️ When the **second argument is a function**, it is treated as `onClose` and the third is ignored.

### Return value `MessageType`

**Callable + thenable**:

```ts
const hide = message.loading('In progress…', 0);
hide();                       // calling closes it
message.loading('In progress…', 2).then(() => message.success('Done'));
```

| Member | Description |
|---|---|
| `()` | Close this message |
| `.then(fn)` | Resolves `true` when terminated: timeout, callable close, destroy, eviction, early cancellation or owner unmount |
| `.promise` | Underlying `Promise<boolean>` |

### `ArgsProps` (input of `message.open`)

| Property | Description | Type | Default |
|---|---|---|---|
| content | Content | `VNodeChild` | — |
| duration | Display duration in seconds; `0` disables auto close | `number` | `3` |
| type | `'info' \| 'success' \| 'error' \| 'warning' \| 'loading'` | — | — |
| key | Unique id; opening the same key **reuses** the notice (content update) | `string \| number` | auto |
| icon | Custom icon (takes precedence; the type class is still applied) | `VNodeChild` | type icon |
| onClose | Called on natural close | `() => void` | — |
| onClick | Click on the notice root | `(e: MouseEvent) => void` | — |
| pauseOnHover | Pause the timer on hover | `boolean` | `true` |
| className / style | Notice root class / style | — | — |
| classNames / styles | Semantic slots (see below) | — | — |

### `ConfigOptions` (`config()` / `useMessage()`)

| Property | Description | Type | Default |
|---|---|---|---|
| top | Offset from the top (number ⇒ px) | `number \| string` | `8` |
| duration | Default duration (seconds) | `number` | `3` |
| maxCount | Max visible; keeps the **last** N | `number` | — |
| rtl | Adds `-rtl` to the list root | `boolean` | from ConfigProvider direction |
| stack | Stacked collapse: `true` or `{ threshold }` | `boolean \| { threshold?: number }` | `false` |
| pauseOnHover | Pause on hover | `boolean` | `true` |
| getContainer | Portal container | `() => HTMLElement \| ShadowRoot` | `document.body` |
| prefixCls | Class prefix | `string` | `apollo-message` |
| transitionName | Motion name | `string` | `{prefixCls}-fade` |
| classNames / styles | Semantic slots | — | — |

### Semantic slots (6)

```
list / listContent              // list level
root / wrapper / icon / title   // notice level
```

> ⚠️ `classNames` / `styles` accept objects. `list` / `listContent` belong to holder config and PureList; per-notice Args and PurePanel accept only notice fields.

### Slots (C8-R2, only the `_InternalPanelDoNotUseOrYouWillBeFired` static panel)

| Slot | Description | Arguments |
|---|---|---|
| content | Rich content (equivalent to the `content` text prop, slot first) | — |
| icon | Custom icon (empty slot = hidden) | — |

> The imperative input `message.open({ content, icon })` keeps `VNodeChild` (programmatic context, no template).

### Type exports

`MessageArgsProps`, `MessageConfigOptions`, `MessageInstance`, `MessageType`,
`MessageNoticeType`, `MessageTypeOpen`, `MessageJointContent`, `MessageSemanticType`.

## Theme (Component Token)

3 tokens (CSS variables `--apollo-message-*`): `zIndexPopup` (`zIndexPopupBase + 1000 + 10` =
**2010** — note this is **not** notification's `+50`) / `contentBg` (`colorBgElevated`) /
`contentPadding` (`(controlHeightLG − fontSize × lineHeight) / 2` px + `paddingSM` px).

## Design notes

### It reuses notification's shared style layer

antd's message is built entirely on rc-notification (`useRcNotification`) and reuses
notification's shared tokens and list-item styles. This repo does the same: the imperative
API and the overlay structure come from `notification/engine/` (our own Vue port of
rc-notification); message only adds "config translation + icons/semantic slots + the
imperative entry point".

### Holder and queue of the imperative path

`message.success()` has no component instance ⇒ state lives on a **module-level singleton**:
the first call creates the holder (mounted on a **detached div**, never attached to the
document) and pushes the task into a queue, which is replayed once the instance is ready.
`config()` **merges** and triggers one sync.

### Style imports

```ts
import '@apollo-design/theme/dist/tokens.css'; // theme variables, required first
import '@apollo-design/ui/message/style.css';  // on demand
// or
import '@apollo-design/ui/style.css';          // all-in-one
```

With a custom `prefixCls` (e.g. `my-app`), emit the CSS yourself via `genMessageStyle('my-app')`.

## FAQ

**Why is there no close button on the notice?**

message passes `closable: false` (same as antd) — messages dismiss themselves by timer.

**Do already visible messages follow a later `config()`?**

Current list presentation follows configuration replacement; `maxCount` is enforced by the next `open`.


Hook holders read the current ConfigProvider prefix for existing notice type and icon classes, while preserving keyed content and explicit user styles. An explicit icon value, including null, false or 0, overrides the type icon. Manual destroy does not call onClose; automatic closure keeps its existing callback contract.


### Vue contract and migration

Call `useMessage` in setup and render its zero-argument holder factory as a component or invoke it to obtain a VNode. Commands before holder mount are queued. Every handle for the same key settles at termination; `true` denotes termination, not successful display. The latest `onClose` still runs only on automatic closure; callable close, destroy, eviction and unmount do not synthesize it.

PurePanel forwards native `class`, `style`, attributes and typed `@click` to its host; replace its old `className` with `class`. Rich content uses `#content` / `#icon`, including `0` and explicit empty content. PureList semantic style maps use `styles`; native `style` styles its host.

Holder configuration and Provider objects are read during rendering, so replacement and removal update existing keyed content without replacing user input nodes. All three component tokens follow the current theme. Numeric list z-index overrides (including `0` and numeric strings) also provide the context used by descendant popups. CSS expressions remain CSS and use the current token for the numeric context.


## component-token (component-token)

Compare the default message with live `ConfigProvider` overrides for its surface, padding and stacking layer. Removing overrides restores the current site theme.

### 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)

Customize message display duration from default `3s` to `10s`.

### 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)

Use `message.useMessage` to get `contextHolder` with context accessible issue. Please note that, we recommend to use top level registration instead of `message` static method, because static method cannot consume context, and ConfigProvider data will not work.

### 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)

Static methods cannot consume Context provided by `ConfigProvider`. Please use hooks version or `App` provided instance first.

### 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)

Display a global loading indicator, which is dismissed by itself asynchronously.

### 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)

Messages of success, error and warning types.

### 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)

Debug usage. Do not use in your production.

### 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)

Stack configuration, disabled by default. Messages will be stacked when the amount is over `threshold`. Only the latest message is shown in the collapsed stack.

### 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)

You can customize the semantic dom style of messages with `classNames` and `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)

`message` provides a promise interface for `onClose`. The above example will display a new message when the old message is about to close.

### 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)

Update message content with unique `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


A modal dialog. Use it when the user must handle a transaction without leaving the page.

## When to use

- When the user should **focus on a single task** (a form, a confirmation, a warning).
- When you need an **imperative** dialog (`Modal.confirm(...)` / `Modal.info(...)`).
- When the dialog must constrain focus (focus trap + focus restore on close).

## Demos

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/modal/demo) (23 files, mirroring antd's demo list).

## API

### Component `<Modal>`

| Prop | Description | Type | Default |
|---|---|---|---|
| open / v-model:open | Whether visible. Cancel/close requests false; OK only notifies | `boolean` | `false` |
| title | Title text; `#title` takes precedence | `string` | — |
| width | Width (accepts a responsive breakpoint object) | `string \| number \| Partial<Record<Breakpoint, string \| number>>` | `520` |
| height | Height | `string \| number` | — |
| loading | Skeleton in the body (**footer is forced off**) | `boolean` | `false` |
| centered | Vertically centered | `boolean` | `false` |
| closable | Close button. `false` hides it; an object may carry `disabled` / `onClose` / `afterClose` | `boolean \| {...}` | `true` |
| mask | Mask. `false` disables it; an object may carry `enabled` / `blur` / `closable` | `boolean \| { enabled?, blur?, closable? }` | `true` |
| okText / cancelText | Text; same-name slots take precedence | `string` | locale (OK / Cancel) |
| okType | OK button type | `'text' \| 'link' \| 'primary' \| 'default' \| 'dashed'` | `'primary'` |
| confirmLoading | OK button loading (**cancelling is blocked while true**) | `boolean` | `false` |
| okButtonProps / cancelButtonProps | OK / Cancel button props; use Vue-native `class` for root styling (not `className` / `rootClassName`) | `ModalButtonProps` | — |
| getContainer | Container; `false` renders **inline** (no portal) | `GetContainer` (Portal; includes Element / ShadowRoot / function / false) | `document.body` |
| zIndex | z-index | `number` | — |
| keyboard | Close on ESC | `boolean` | `true` |
| scrollLock | Lock body scroll while open | `boolean` | `true` |
| forceRender | Render even when closed | `boolean` | `false` |
| destroyOnHidden | Unmount on close | `boolean` | `false` |
| mousePosition | Origin of the zoom motion | `{ x, y } \| null` | — |
| focusable | Focus behaviour: `{ trap?, focusTriggerAfterClose? }` | — | `trap` follows `mask`; `focusTriggerAfterClose: true` |
| panelRef | Panel root node (forwarded to watermark) | `Ref \| Function` | — |
| classNames / styles | Nine semantic targets; objects or functions receiving `{ props: ModalProps }` from the current render | `ModalProps["classNames"] / ModalProps["styles"]` | — |

**deprecated (dev warnings)**: `bodyStyle` → `styles.body`; `maskStyle` → `styles.mask`;
`destroyOnClose` → `destroyOnHidden`; `focusTriggerAfterClose` → `focusable.focusTriggerAfterClose`;
`maskClosable` → `mask.closable`; `autoFocusButton` → `focusable.autoFocusButton`.

### Events and slots

| Event | Payload | Meaning |
|---|---|---|
| `update:open` | `boolean` | Cancellation/close request. Controlled refusal preserves the actual open state |
| `ok` | `Event` | OK notification; manage asynchronous loading and closing in the parent |
| `cancel` | `Event` | Cancel button, close button, mask or Escape |
| `afterClose` | none | Leave motion completed |
| `afterOpenChange` | `boolean` | Open/close motion completed |

| Slot | Scope | Content |
|---|---|---|
| default | — | Body |
| title / okText / cancelText / closeIcon | — | Named content; empty slots hide it |
| footer | `{ OkBtn, CancelBtn }` | Stable action components using current button configuration and events |
| modalRender | `{ ModalPanel }` | Stable current panel component; wrap it with `<component :is="ModalPanel" />` |

Native `class`, `style`, `id`, ARIA, data attributes and listeners land on the actual panel.
`panelRef` receives `HTMLElement | null`; Modal does not expose focus/blur methods.
An omitted `open` starts closed; withdrawing a controlled `open` preserves its last accepted value.

### Imperative (static methods)

| Method | Description |
|---|---|
| `Modal.confirm(config)` / `info` / `success` / `error` / `warning` / `warn` | Open a confirmation dialog. `warning` and `warn` are **the same function** |
| `Modal.destroyAll()` | Close every imperative instance |
| `Modal.useModal()` | Returns `[api, contextHolder]`; `api` exposes the same six methods |
| `Modal.config({ rootPrefixCls })` | **Deprecated** — use `ConfigProvider.config` |
| `Modal._InternalPanelDoNotUseOrYouWillBeFired` | Private panel (**no portal, no mask, no motion**) for docs and debugging |

Imperative instance (returned by `Modal.confirm(...)` / `useModal()`):

| Member | Description |
|---|---|
| `destroy()` | **Closes** (runs the leave motion, then unmounts via `afterClose`) — not an immediate unmount |
| `update(config)` | Update the config (shallow merge, or pass a function) |
| `then(resolve, reject)` | Hook instances only: `await api.confirm(config)` resolves `true` for accepted OK and `false` for cancellation, destruction or holder/owner teardown |

`onOk(close)` and `onCancel(close)` are imperative services. Returning a promise enables
loading and closes on success; rejection keeps the dialog open. Programmatic `footer(originNode,
{ OkBtn, CancelBtn })`, `modalRender(node)`, `afterClose` and `afterOpenChange` remain config functions.
Closing/closed instances ignore updates and unregister from `destroyAll` after cleanup. Commands
issued before the hook holder mounts are retained; destroying such a command prevents mounting.

`ModalFuncProps` adds `content` / `icon` / `type` / `okCancel` / `autoFocusButton` /
`focusable.autoFocusButton` on top of `ModalProps`, and narrows `width` to `string | number`.

### Semantic slots (9)

```
root / container / wrapper / mask / header / title / body / footer / close
```

⚠️ Inside `ConfirmDialog`, `body` is lifted out and re-attached to `-confirm-content`.

## Theme (Component Token)

Six public tokens (overridable via `theme.components.Modal`): `headerBg`(transparent) /
`footerBg`(transparent) / `titleLineHeight`(`lineHeightHeading5`) /
`titleFontSize`(`fontSizeHeading5`) / `titleColor`(`colorTextHeading`) /
`contentBg`(`colorBgElevated`).

There are also **12 internal** tokens (emitted as CSS variables but outside the public
type surface): `contentPadding` / `headerPadding` / `headerBorderBottom` /
`headerMarginBottom` / `bodyPadding` / `footerPadding` / `footerBorderTop` /
`footerBorderRadius` / `footerMarginTop` / `confirmBodyPadding` /
`confirmIconMarginInlineEnd` / `confirmBtnsMarginTop` — each switching between two
value sets under the `wireframe` theme.

## Focus (hard a11y requirements)

1. **Focus trap**: enabled only when `focusable.trap` (defaults to the `mask` flag),
   `visible`, and the container's `position: fixed` are all true;
2. **Focus restore**: focus returns to the previously active element on close
   (`focusable.focusTriggerAfterClose`, default `true`).
   ⚠️ Upstream gates this on `mask` as well — **a dialog without a mask does not restore focus**
   (we follow upstream);
3. **`autoFocusButton`**: confirmation dialogs focus the OK button by default.
   `focusable.autoFocusButton: null` explicitly disables button autofocus (the deprecated top-level form also supports `null`).

## Known differences from antd

See `COMPATIBILITY.md` for the retained differences: no `ContextIsolator`
(form / space isolation); no cssinjs hash / `-css-var` classes; the imperative path
mounts a Vue app into a detached `div` (React uses a `DocumentFragment`); `holderRender`
is not implemented.

## Migration

Replace ordinary `afterClose` / `afterOpenChange` props with `@after-close` /
`@after-open-change` (`onAfterClose` / `onAfterOpenChange` in `h()`). `@ok` and `@cancel`
are typed Vue events. Replace ordinary `modalRender` with `#modalRender`; use the scoped
`ModalPanel` component. Ordinary footer content uses `#footer` and its scoped buttons.
Imperative configuration services and programmatic renderers retain their responsibilities.

The ordinary `focusTrap` declaration had no runtime consumer; use `focusable.trap`.
The imperative config's inherited `open` field also had no consistent lifecycle consumer
and has been removed: calling a method opens, `destroy()` closes, and `update()` changes
only the content and effective configuration of a live session. It does not reopen one.

Imperative `update({ confirmLoading: true })` explicitly shows the OK loading state and
blocks clicking it. Updating to `false` restores the business promise's own loading state;
an unsettled promise continues showing its spinner.


## async (async)

Asynchronously close a modal dialog when the OK button is pressed.

### 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 modal.

### 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)

Passing props to the buttons, e.g. changing the base 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)

Modify component token alone: title line height, font size, and font color.

### 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)

Use `confirm()` to show a confirmation modal dialog.

### 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)

Confirm dialogs for side effects such as navigation.

### 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)

Specify the origin of the zoom animation with `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)

Open a dark modal containing a switch, slider and timeline, all inheriting `darkAlgorithm`. Use the switch to disable the slider.

### 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)

A more complex example with a customized footer.

### 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)

Custom footer render function, reusing the default `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)

Use the `useModal` hook to get an updatable / destroyable modal instance.

### 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)

Set the `loading` prop to show a skeleton in the content area.

### 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)

Customize the button text with `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)

Manually update and remove a modal with a timer.

### 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)

Three mask forms: blurred / dimmed / none.

### 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)

Customize the rendered node with the `#modalRender` scoped slot and the title slot via semantic classNames.

### 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 modals, three levels deep.

### 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)

Control the vertical position of the dialog with `style.top` and `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)

Debug panel (`_InternalPanelDoNotUseOrYouWillBeFired`) — no portal, no mask, no motion.

### 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)

Various types of message dialogs, invoked via static methods.

### 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)

Customize each area of the dialog via the `classNames` / `styles` semantic slots (function form supported).

### 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)

Set `width` to customize the dialog 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 style (`wireframe` theme).

### 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


Display global notifications in six placements. Imperative API (`notification.success({ title })`),
the overlay is portaled.

## When to use

- A heavier notification than `message`: title + description + action buttons.
- Notifications should appear in a specific placement (topRight / bottomRight / top…).
- An auto-close countdown bar is needed (`showProgress`).
- ⚠️ Prefer `notification.useNotification()` and its `contextHolder`: static methods **cannot
  consume context**.

## Demos

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/notification/demo) (14 demos, covering the main antd scenarios
duration / hooks / placement / progress-color / render-panel / show-with-progress /
stack / style-class / update / with-btn / with-icon.

## API

### Static methods

| Method | Description | Signature |
|---|---|---|
| `notification.success` / `info` / `warning` / `error` | Open a notification of that type | `(config: ArgsProps) => void` |
| `notification.open` | Open with full config | `(config: ArgsProps) => void` |
| `notification.destroy` | Close one (by key) or all | `(key?: string \| number) => void` |
| `notification.config` | Global defaults (**merged**) | `(config: GlobalConfigProps) => void` |
| `notification.useNotification` | Hook form | `(config?) => [NotificationInstance, () => VNode]` |
| `notification._InternalPanelDoNotUseOrYouWillBeFired` | Private: single static panel | component |
| `notification._InternalListDoNotUseOrYouWillBeFired` | Private: static list | component |

> ⚠️ **`open()` returns `void`** — unlike `message`, notification has no thenable/callable
> handle; it also has no `loading` type (`IconType` has 4 values).

### `ArgsProps`

| Property | Description | Type | Default |
|---|---|---|---|
| title | Title | `VNodeChild` | — |
| description | Description; wrapped in `-notice-section` together with `title` | `VNodeChild` | — |
| actions | Action area | `VNodeChild` | — |
| type | `'success' \| 'info' \| 'error' \| 'warning'` | — | — |
| placement | One of six placements; **per-notice wins over global** | `NotificationPlacement` | `'topRight'` |
| duration | Seconds; `0` / `false` ⇒ never auto close | `number \| false` | `4.5` |
| showProgress | Show the auto-close countdown bar | `boolean` | — |
| pauseOnHover | Pause the timer on hover | `boolean` | `true` |
| closable | Close button. `false` / `null` ⇒ **no button at all** | `boolean \| null \| { closeIcon?, disabled?, onClose? }` | `true` |
| closeIcon | Custom close icon; `null` ⇒ no button (upstream semantics) | `VNodeChild` | — |
| icon | Custom icon (when given, `-notice-icon-{type}` is **not** applied) | `VNodeChild` | type icon |
| role | ARIA role of the notice root | `'alert' \| 'status'` | `'alert'` |
| key | Unique id; opening the same key reuses the notice | `string \| number` | auto |
| onClose | Latest subscription, called on button/timeout closure; destroy, eviction and unmount remain silent | `() => void` | — |
| onClick | Click subscription | `(event: MouseEvent) => void` | — |
| className / style / classNames / styles / props | Notice root class/style, per-notice semantic objects and native root attributes | — | — |
| message / btn | ⚠️ Deprecated: use `title` / `actions` | — | — |

### Slots (C8-R2, only the `_InternalPanelDoNotUseOrYouWillBeFired` static panel)

| Slot | Description | Arguments |
|---|---|---|
| title | Rich title (equivalent to the `title` text prop, slot first) | — |
| message | ⚠️ Deprecated alias, same as `title` | — |
| description | Rich description (equivalent to the `description` text prop, slot first) | — |
| icon | Custom icon (empty slot = hidden) | — |
| actions | Action area (empty slot = hidden) | — |
| btn | ⚠️ Deprecated alias, same as `actions` | — |
| closeIcon | Custom close icon (empty slot = hidden) | — |

> The imperative input `notification.open({ title, description, icon, actions, closeIcon })` keeps
> `VNodeChild` (programmatic context, no template).

### `GlobalConfigProps` (`config()`) and `NotificationConfig` (`useNotification()`)

`top` / `bottom` / `duration` / `showProgress` / `pauseOnHover` / `prefixCls` / `getContainer` /
`placement` / `closeIcon` / `closable` / `rtl` / `maxCount` / `props`; the hook config also has
`stack` (`boolean | { threshold }`, **defaults to `{ offset: 8 }` ⇒ stacked by default**) and
`classNames` / `styles`.

### Semantic slots (11)

```
list / listContent                                                                    // list level
wrapper / root / title / description / actions / icon / section / close / progress    // notice level
```

> ⚠️ `classNames` / `styles` accept objects. `list` / `listContent` belong to NotificationConfig and PureList; per-notice Args and PurePanel accept only notice fields.

### Type exports

`NotificationArgsProps`, `NotificationGlobalConfigProps`, `NotificationConfig`,
`NotificationInstance`, `NotificationPlacement`, `NotificationIconType`, `NotificationSemanticType`.

## Theme (Component Token)

7 keys (CSS variables `--apollo-notification-*`), 3 of which have defaults:

| token | Value |
|---|---|
| `zIndexPopup` | `zIndexPopupBase + CONTAINER_MAX_OFFSET(1000) + 50` = **2050** (⚠️ message uses `+10`) |
| `width` | `384` |
| `progressBg` | `linear-gradient(90deg, colorPrimaryBorderHover, colorPrimary)` |
| `colorSuccessBg` / `colorErrorBg` / `colorInfoBg` / `colorWarningBg` | `undefined` by default (the product uses a `var()` with fallback) |

## Design notes

### It shares the notification kernel with `message`

Both are built on `notification/engine/` (our own Vue port of rc-notification); the difference is
only in config translation and the notice's inner semantics (notification has title + description +
actions + close button; message is a single line of text).

### Stacked by default

`DEFAULT_STACK_CONFIG = { offset: 8 }` ⇒ the list root always carries `-stack`, and notifications
collapse beyond the threshold (3 by default). `message` defaults to `false` — the easiest of the
two to mix up.

### Style imports

```ts
import '@apollo-design/theme/dist/tokens.css';      // theme variables, required first
import '@apollo-design/ui/notification/style.css';  // on demand
// or
import '@apollo-design/ui/style.css';               // all-in-one
```

## FAQ

**Why does the close button sometimes have no icon?**

`closable: false` or `closeIcon: null` **removes the whole button** (upstream semantics); use
`closable: { closeIcon: null }` for "button without icon".

**Is `duration: 0` different from `duration: false`?**

No — both are normalized to `false` (never auto close).

**What happens when the same key is opened twice?**

The notice is reused and its content updated (see the `update` demo); no new notice is added.


Hook holders keep existing notices in place when Provider defaults change. Type/icon/close classes follow the current prefix, the default accessible close label follows the current locale, and an explicit closable aria-label takes priority. Content and user styles remain keyed. closable.disabled disables the native close button.

PurePanel `closable` is visual configuration (icon, disabled state and accessible label). Use its typed `@close` event; the previously unconsumed nested `closable.onClose` field is removed. Imperative Args/hook/global subscriptions retain their existing behavior.


### Vue contract and migration

Call `useNotification` in setup and render its zero-argument holder factory as a component or invoke it to obtain a VNode. Early commands are queued until that holder is ready and discarded on owner unmount. Updating an existing key keeps its content identity and restarts its duration; numeric and string keys remain distinct.

PurePanel forwards native `class`, `style`, attributes and typed `@click` / `@close` to its real host. Replace its old `className` with `class`. Rich content uses named slots and preserves `0` and explicit empty content. PureList semantic style maps use `styles`; native `style` styles its host. `getContainer` accepts an HTMLElement or ShadowRoot.

Current holder and Provider objects can be replaced or removed; all seven tokens and locale defaults follow the current context. Numeric list z-index overrides (including `0` and numeric strings) also provide descendant popup context. CSS expressions stay unchanged and use the current token for numeric context. Static methods read global ConfigProvider services and do not inject the calling component’s context.


## basic (basic)

Static methods cannot consume Context provided by `ConfigProvider`. Please use hooks version or `App` provided instance first.

### 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)

Set notification width, progress and status surfaces through `ConfigProvider`. Toggle the local component tokens to compare them with the inherited theme.

### 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)

Customized 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)

`duration` can be used to specify how long the notification stays open. After the duration time elapses, the notification closes automatically. If you set duration to 0, the notification box will never close automatically.

### 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)

Use `notification.useNotification` to get `contextHolder` with context accessible issue. Please note that, we recommend to use top level registration instead of `notification` static method, because static method cannot consume context.

### 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)

A notification box can pop up from `top`, `bottom`, `topLeft`, `topRight`, `bottomLeft` or `bottomRight`.

### 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)

Customize the progress bar with the `Notification.progressBg` component token. Keep the notification holder inside the local `ConfigProvider` so its overlay inherits that theme.

### 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)

Debug usage. Do not use in your production.

### 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 the progress bar of the auto-close countdown.

### 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)

Stack configuration. Notifications will be stacked when the amount is over `threshold`. Only the latest notification is shown in the collapsed stack.

### 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)

You can customize the semantic dom style of notifications with `classNames` and `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)

Update content with unique `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)

To customize the text of the close button.

### 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)

An icon can be set.

### 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

A long list can be divided into several pages, and only one page will be loaded at a time.

## When To Use

- When it will take a long time to load/render all items.
- When the data set is too large to show at once.
- When users need to jump between pages quickly.

## Import

```ts
import { Pagination } from '@apollo-design/ui';
```

## Examples

























## API

### Pagination

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| 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` | —— |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| `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)` |

### Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| `itemRender` | 自定义每一项（替代 `itemRender` prop） | `{ page, type, element }` |
| `total` | 自定义总数展示（替代 `showTotal` prop） | `{ total, range }` |
| `sizeChanger` | 自定义尺寸切换器（替代 `sizeChangerRender` / antd 的 `components.sizeChanger`） | `{ value, onSizeChange, onChange, disabled, className, options, 'aria-label' }` |

### Keyboard

| Key | Behavior |
| --- | --- |
| Enter | 在页码 / 上一页 / 下一页 / 跳页项上触发 |
| Enter（快速跳转输入框） | 跳到输入页；↑ / ↓ 在简化模式下是 ∓1 |

`current` and `pageSize` are independently controlled. Defaults initialize uncontrolled state once. External updates emit no events; releasing control retains the last received value and discards rejected requests. An uncontrolled page stays clamped after total shrinks and grows; a controlled page follows its input. Size changes notify in this order: `update:pageSize`, `showSizeChange`, `update:current`, `change`. The `showSizeChange` page is the previous page.

Simple input shows the actual model after Enter or blur; empty input restores the current page. Moving focus to this instance's page controls, including custom slot buttons, lets that control handle navigation. Moving to another pagination still commits the quick jumper. `goButton` accepts Vue content including `0`; `true` uses the default button, while `false` / `null` / `undefined` hide confirmation content. Enter and arrow keys support `KeyboardEvent.key`; an Enter already cancelled by slot content is respected. Disabled controls and the zero-total placeholder leave the tab order and report `aria-disabled`. Disabled size callbacks, unchanged sizes and non-positive/non-integer size requests do not emit updates.

Select configuration in `showSizeChanger` accepts native `class` strings, arrays and objects. Replace the undeclared `showSizeChanger.className` spelling from older tests with `showSizeChanger.class`; there is no compatibility alias. `classNames.item` / `styles.item` still target pagination items. There are no public exposed methods; the Vue instance's `$el` references the current root `<ul>` (a comment when hidden).

> ⚠️ **尺寸切换器注入点有两个字段名**：rc 的 `sizeChangerRender` 实参叫 `onSizeChange`，
> antd 的 `components.sizeChanger` 叫 `onChange` —— 本仓**两个都给**（同一个函数），
> 照哪份文档写都能用（见 `COMPATIBILITY.md` 的 U14 上下文）。

## Design Token

| Token | Default (light) | Description |
| --- | --- | --- |
| `itemBg` / `itemActiveBg` / `itemLinkBg` / `itemInputBg` | `#ffffff` | Page / active page / regular previous-next button / simple input backgrounds |
| `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`'s `theme.components.Pagination` accepts these 12 component tokens. Dimensions accept CSS strings or numbers in pixels; `miniOptionsSizeChangerTop` also accepts negative offsets. Replacing or removing overrides derives fallbacks from the current global tokens. Native root `style` takes priority over semantic root styles, followed by theme variables. A custom `prefixCls` uses the corresponding component variable namespace and requires matching caller-provided styles.

Quick-jumper font, padding and focus variables derive from current global tokens and are not additional Pagination component override fields. The size Select owns its own tokens. With no active source theme, static CSS and ancestor CSS variables retain control. Theme updates write root variables; style rules remain static.

Content uses native #itemRender/#total/#sizeChanger slots. The three renderer props are removed directly without compatibility or deprecation layers. Item slots cover page/prev/next/jump-prev/jump-next. Empty slots suppress defaults; conditional addition/removal and reactive updates work after mount. PaginationItemSlotProps/PaginationTotalSlotProps/PaginationSlots export the contracts. Native root id/title/events and string/object/array styles are forwarded and merged with semantic root styles using Vue rules.


## Basic (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="{ 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)

尺寸切换器、快速跳转和原生总数槽组合。

### 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 (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 (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` 简化模式：只有上一页/下一页 + `当前 / 总数`（可输入）。

### 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 (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 (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 (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)

`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>
```

## Custom item render (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>
```

## Custom size changer (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>
```

## Component 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>
```

## Semantic styles (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>
```

## Dynamic native slots (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

A simple and compact confirmation dialog of an action. Compared with `Popover`, it ships with built-in OK / Cancel buttons.

## When To Use

A simple and compact dialog used for asking confirmation of an action from the user.

## Examples





















## API

### PopconfirmProps

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Title data (`0` is valid); template content uses `#title` | VNodeChild | - |
| description | Description data; template content uses `#description` | VNodeChild | - |
| disabled | Disables trigger requests to open, without emitting `openChange` | boolean | false |
| open | Whether the floating layer is open (controlled) | boolean | - |
| defaultOpen | Whether the floating layer is open by default | boolean | false |
| trigger | Trigger mode | string \| string[] | 'click' |
| placement | Position of the floating layer | TooltipPlacement | 'top' |
| okText | Text of the OK button; falls back to locale when empty | string | OK |
| okType | Type of the OK button | LegacyButtonType | 'primary' |
| cancelText | Text of the Cancel button; falls back to locale when empty | string | Cancel |
| okButtonProps | Props of the OK button; use Vue-native `class` for root styling | PopconfirmButtonProps | - |
| cancelButtonProps | Props of the Cancel button; use Vue-native `class` for root styling | PopconfirmButtonProps | - |
| showCancel | Whether to show the Cancel button | boolean | true |
| icon | Icon data; `false` hides it. Template composition uses `#icon` | VNode \| string \| false | ExclamationCircleFilled |
| onConfirm | Called when OK is clicked; a returned Promise delays closing | (e?: MouseEvent) => void \| Promise | - |
| onCancel | Called when Cancel is clicked | (e?: MouseEvent) => void | - |
| classNames | Semantic class names (root / container / arrow / icon / title / content) | object or function | - |
| styles | Semantic styles (same slots) | object or function | - |

`onConfirm` / `onCancel` remain business callback props. A synchronous confirmation return requests closing. A returned Promise keeps the button loading until it settles: success requests closing; rejection keeps the panel open and reaches Vue error handling. After accepted hiding, the next opening starts a new confirmation session, and an older Promise cannot close the new panel. Callers clean up business requests and timers on cancellation and unmount. A refused controlled close keeps the current operation.

### Slots

| Name | Content |
| --- | --- |
| default | Trigger element (Popconfirm only) |
| title / description | Title / description, taking precedence over the matching prop |
| icon | Icon content, overriding icon data or the default; empty slots omit the wrapper |
| okText / cancelText | Button content, taking precedence over the string prop and locale |

`PopconfirmSlots` is exported. All five content slots also work in `PopconfirmPurePanel`. Present slots override all fallbacks, including empty content; removing a slot restores the prop, default icon or locale. Slots are read during render, and icon changes preserve the body nodes and input state. Render-function props are removed directly; async confirmation callbacks remain supported. See the [migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/overlay-content-slots.md).

### Native class/style

Native class/style apply to the popup root. Style accepts strings, objects and mixed arrays, overriding matching semantic root styles. PopconfirmPurePanel routes root/container/arrow classNames/styles to its static panel and icon/title/content to the confirmation body; native style applies only to the panel root and does not override styles.container.

### Events

| Event | Description | Payload |
| --- | --- | --- |
| openChange | Requests a new open state; a controlled parent decides whether to accept it | `(open: boolean)` |
| update:open | Synchronization request for `v-model:open` | `(open: boolean)` |
| popupClick | Click on the confirmation body; also supported by PurePanel | `(event: MouseEvent)` |
| afterOpenChange | Opening or closing animation completed | `(open: boolean)` |

Templates use `@open-change` / `@popup-click` / `@after-open-change`, including `.once` and listener arrays. JSX / `h()` uses `onOpenChange` / `onPopupClick` / `onAfterOpenChange`. Replace old `:on-open-change` / `:on-popup-click` function props directly with events; there is no compatibility channel. The `onConfirm` / `onCancel` business callback props remain unchanged, including Promise returns from confirmation.

Native class/style apply only to the popup root; other native attributes and events target the trigger element. Removing controlled `open` preserves its last accepted value, without applying a request refused by the parent.

### Theme Variables

| Token | Description | Default |
| --- | --- | --- |
| zIndexPopup | z-index of the popup | zIndexPopupBase + 60 |

`theme.components.Popconfirm.zIndexPopup` and existing global visual tokens consume the current theme, including nested themes, replacement and removal; `0` is valid. Popconfirm and its static panel consume their own component configuration. Independent Popover / Tooltip instances in the content keep their own configuration. The wrapper shares one layer calculation. The final numeric root `zIndex`, including `0` and numeric strings, takes precedence and supplies descendant layers; removing it restores the dedicated `zIndex` prop or automatic layer. Conditional `undefined` or empty-string layers and native `false/null/undefined` release the override. Automatic descendant layering from `calc/var` remains deferred.

[Native panel style migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/overlay-native-styles.md).


## Basic (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 text (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>
```

## Custom icon (icon)

Compose icon components and current content with the native icon slot. A present slot overrides icon data, including empty content. Removing it restores the default icon or data prop. The static preview uses false, so removing its slot hides the icon while preserving the body input.

### 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 close (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 (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 (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 (render-panel)

Native title, description and button slots support conditional presence, updates and empty content. Only removing a slot restores the prop or locale. Native string styles merge with semantic root styles. The theme button changes the current `Popconfirm.zIndexPopup`; removing the override restores the default.

### 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>
```

## Semantic classNames & styles (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 (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


点击/鼠标移入时弹出气泡卡片。

## When To Use

- A bubble card with title and content for further explanation.

## API

### Props

继承 [Tooltip](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/tooltip/index.zh-CN.md) 的全部 props，另有：

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | Title data (`0` is valid); template content uses `#title` | `TooltipContent` (VNodeChild) | — |
| content | Body data (`0` is valid); template content uses `#content` | `TooltipContent` (VNodeChild) | — |
| classNames / styles | 语义槽 `root / container / arrow / title / content`（含函数式） | — | — |

⚠️ 受控 `open` 时不做 noTitle 压制（antd 口径）：title/content 均空仍会开空浮层。

### 插槽

| 名称 | 说明 |
|---|---|
| default | 触发元素 |
| title / content | Title / body; a present slot overrides its prop, including empty content |

`PopoverSlots` is exported. Both Popover and PopoverPurePanel read current slots during render, including conditional additions, removals and content updates. Render-function props are removed directly; see the [migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/overlay-content-slots.md).

### Native class/style

Popover applies native class/style to the popup root. Style accepts strings, objects and mixed arrays, overriding matching styles.root values until removed. Other native attrs and listeners keep Tooltip's trigger-element target. PopoverPurePanel applies attrs and native class/style to its own root, without duplicating styles on the container. Use styles.container/arrow and matching classNames for individual sections.

The final numeric root layer, including `0` and numeric strings, also supplies descendant Tooltip/Popover/Popconfirm layers and takes precedence over the dedicated `zIndex` prop. Conditional `undefined` or empty-string layers and native `false/null/undefined` release the override. Automatic descendant layering from `calc/var` remains deferred; see Tooltip's native style contract.

### Events

| Event | Payload | Meaning |
|---|---|---|
| update:open | `boolean` | `v-model:open`; the caller decides whether to accept a controlled proposal |
| open-change | `boolean` | Opening or closing proposal, sent with the model event |
| after-open-change | `boolean` | Actual opening or closing animation completion |
| popup-click | `MouseEvent` | Original click event from popup content |

Notifications use Vue emits, including `.once` and listener arrays. `h()` listeners use `onOpenChange`, `onAfterOpenChange` and `onPopupClick`; they are no longer called manually as function props. `PopoverEmits` is exported. The old `afterOpenChange` callback prop is removed.

### Expose

`forceAlign()`, `nativeElement: HTMLElement | null` and `popupElement: HTMLDivElement | null` are described by `PopoverRef`. The element fields are current DOM properties; `popupElement` becomes `null` after removal.

### Current configuration and theme

Popover and PopoverPurePanel consume the current `ConfigProvider.components.popover` classes, semantic styles and root styles. Tooltip's component configuration does not leak into them. PurePanel supports `title`, `content`, `color`, `placement`, `prefixCls`, `classNames` and `styles`, with the same content-slot contract.

`theme.components.Popover` supports these numeric tokens. Replacing, nesting or removing theme configuration updates the actual popup and static panel while preserving content inputs and focus. Native and semantic styles can still override the corresponding CSS variables.

| Token | Default | Meaning |
|---|---|---|
| titleMinWidth | `177` | Minimum title width in px |
| zIndexPopup | Global `zIndexPopupBase + 30` | Popup layer; explicit `zIndex` and parent layering still apply |
| innerPadding | `12` | Container padding in px |
| titleMarginBottom | `8` | Title bottom spacing in px |

Existing Tooltip aliases `overlayClassName`, `overlayStyle`, `overlayInnerStyle` and `destroyTooltipOnHide` follow their inherited contracts. Prefer `classNames.root`, `styles.root/container` and `destroyOnHidden`. Wireframe remains a recorded limitation.

## 设计说明

- Tooltip / `_internal/trigger.ts` owns popup lifecycle and positioning. Popover owns its content, events, Provider configuration and tokens ([historical analysis](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/analysis/popover.md)).
- 与 antd 的已知差异见组件 README。

[Native panel style migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/overlay-native-styles.md).


## arrow (arrow)

The arrow can be hidden or point at the center.

### 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)

After setting `arrow.pointAtCenter`, the arrow points at the center of the target element.

### 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)

The most basic example. The size of the floating layer depends on the contents region.

### 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)

Customize title width, padding and title spacing with the current ConfigProvider's `theme.components.Popover`. Both panels update when the button is clicked.

### 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)

Controlled visibility.

### 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)

Bind both hover and click triggers.

### 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)

There are 12 placement options.

### 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)

Render a static popover panel via PurePanel. Toggle, update or empty its title slot while preserving the body input. Native string styles merge with semantic root styles.

### 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)

The popup follows the target element while scrolling. The demo scrolls within its own viewport without moving the surrounding document.

### 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)

Customize container and content via styles, in object or function form.

### 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)

Mouse enter, focus and click.

### 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 theme is not supported (D84); rendered with the default theme.

### 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


Display the current progress of an operation.

## When To Use

- Show the current progress (uploading, loading, step completion).
- Line / circle / dashboard types, plus step segments.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/progress/demo) (17 demos, one-to-one with the antd user-visible demos).

## API

### Props

| Prop | Description | Type | Default |
|---|---|---|---|
| type | Type | `'line' \| 'circle' \| 'dashboard'` | `'line'` |
| percent | Percentage | `number` | `0` |
| format | Content formatter (fn prop) | `(percent?, successPercent?) => VNodeChild` | `${n}%` |
| status | Status | `'normal' \| 'exception' \| 'active' \| 'success'` | auto success at 100 |
| showInfo | Show indicator text | `boolean` | `true` |
| strokeColor | Stroke color (gradient object supported) | `string \| string[] \| ProgressGradient` | — |
| railColor | Rail color | `string` | — |
| strokeLinecap | Line cap | `'round' \| 'butt' \| 'square'` | `'round'` |
| strokeWidth | Line/step height; circle stroke as a percentage of its diameter | `number` | line 8 / circle max(6, 3/width×100) |
| size | Preset, number, [w,h], or object | `'medium' \| 'middle' \| 'small' \| 'default' \| number \| [number \| string, number] \| { width?: number; height?: number }` | `'medium'` |
| success | Success segment | `{ percent?, strokeColor? }` | — |
| steps | Step count | `number \| { count, gap }` | — |
| gapDegree / gapPlacement | Dashboard gap | `number` / union | 75 / `'bottom'` |
| percentPosition | Indicator position | `{ align?, type? }` | `{ align: 'end', type: 'outer' }` |
| rounding | Step rounding fn | `(step: number) => number` | `Math.round` |

> Deprecated: `width` -> `size`, `trailColor` -> `railColor`, `gapPosition` ->
> `gapPlacement`, `size="default"` -> `size="medium"` (all warn).

### Semantic (classNames / styles)

`root` / `body` / `rail` / `track` / `indicator` (object and function variants).

`rail` targets the line rail or the continuous SVG circle rail. Step items use
`track`; they have no separate rail node. Circle rail styles apply to the actual
SVG element. Semantic functions receive the current `{ props }`.

For lines, numeric widths in scalar, tuple and object size values use px, with the
corresponding rail height; nonpositive width fills the available space. Information can make the body
taller than the rail, so size height describes the rail.
Tuple widths also accept CSS lengths such as `['65%', 12]`. For line steps, the
tuple width is each segment's width. Circles/dashboard accept a number or preset;
explicit `size` takes precedence over the existing deprecated `width` prop.
`middle` remains supported alongside `medium`.

`steps.gap` controls circle/dashboard segment spacing. `rounding` controls line
step rounding. A `strokeColor` array supplies line-step colors; other forms use
its first color. Gradients accept `from`/`to` or percentage stops; `direction`
controls the line gradient. Circle percentage stops are ordered by position.

`percentPosition` updates both the indicator host and its alignment/color classes
when replaced or removed. `format` remains a value-formatting callback, receives
the clamped percentage and success percentage, and can return any Vue content.
There are no public slots, component events, models or exposed methods.

Inner line text chooses a readable black/white foreground against its current
opaque solid track, including theme/status colors. Explicit `styles.indicator.color`
still wins. Authors pair text with custom gradients, alpha colors or overridden
track backgrounds. This directly corrects the development default's insufficient
contrast on bright tracks; there is no compatibility switch or deprecation period.

Native `class`, all Vue `style` forms, DOM attributes and listeners target the
root progressbar. A native listener runs once per DOM event. Styling precedence
is theme variables, Provider `styles`, Provider `style`, local `styles`, then
native root `style`; semantic classes are combined. ConfigProvider
`components.progress` supports `className`, `style`, `classNames` and `styles`,
including reactive replacement/removal. Current prefix and direction are observed.

The six existing component tokens are read from `theme.components.Progress`:
`circleTextColor`, `defaultColor`, `remainingColor`, `lineBorderRadius`,
`circleTextFontSize`, `circleIconFontSize`. Numeric `lineBorderRadius` uses px;
the other values are CSS strings. Current theme aliases and nested overrides
apply in SSR and after updates. Default circle success segments use the theme's
success color; explicit success colors keep precedence.

The actual progressbar uses success.percent when provided, otherwise percent, for
`aria-valuenow`. Finite fractions are preserved and clamped to 0–100; non-finite
values become 0. Internal accessibility values take precedence over same-name native
attrs. Supply the accessible name through aria-label / aria-labelledby. Existing
integer-based status derivation and explicit normal status retain their behavior.

## Design notes

- **Self-built SVG circle core** (H5, no `@rc-component/progress`): dasharray/dashoffset
  math reverse-engineered from the antd real DOM.
- **Gradient circle** uses the mask + foreignObject conic approach.
- **<=20px circle**: indicator shown via Tooltip.
- **6 Component Tokens**; the `--progress-line-stroke-color` variable has no component
  prefix (verbatim from the antd output).


## circle (circle)

Circle progress.

### 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)

Micro circle with 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)

Mini size circular progress.

### 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 with 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)

Dashboard with customizable `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 progress value.

### 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)

Custom content via `format`.

### 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)

Gradient progress.

### 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)

Indicator position via `percentPosition`.

### 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)

Plain line progress.

### 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)

Small size line progress.

### 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)

Square linecap.

### 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.

### 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)

Semantic `classNames` / function `styles`.

### 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)

All `size` variants.

### 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)

Step progress bar.

### 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)

Semantic `classNames` / `styles` (object).

### 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


Encode text or segments using canvas or SVG. The caller controls status; the component has no request manager or v-model.

## Demos

Five real examples: [basic](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/qr-code/demo/basic.vue), [custom](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/qr-code/demo/custom.vue), [status](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/qr-code/demo/status.vue), [svg](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/qr-code/demo/svg.vue), [component-token](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/qr-code/demo/component-token.vue).

## API

| Prop | Description | Type | Default |
|---|---|---|---|
| value | Content; missing or empty strings render nothing and warn in development | string \| string[] | — |
| type | Drawing mode | canvas \| svg | canvas |
| size | Positive finite logical size; invalid values fall back to 160 | number | 160 |
| icon | Center image URL; canvas excavates after loading | string | — |
| iconSize | Positive finite dimensions; missing/invalid axes fall back to 40 | number \| { width?, height? } | 40 |
| color | Neutral image foreground from the default theme | string | default colorText |
| bgColor | Explicit image and host background; when omitted pixels are transparent over a white host. Explicit transparent makes the host transparent | string | — |
| errorLevel | Error correction; L with an icon warns in development | L \| M \| Q \| H | M |
| status | Active has no cover | active \| expired \| loading \| scanned | active |
| bordered | Show border | boolean | true |
| marginSize | Quiet-zone modules, floored and clamped nonnegative; nonfinite values fall back to 0 | number | 0 |
| boostLevel | Permit the encoder to increase correction | boolean | encoder default |
| title | Actual image name in both modes; SVG also renders title | string | QR code |
| prefixCls | Current class prefix; preload matching static CSS | string | apollo-qrcode |
| classNames / styles | Root and cover semantic classes/CSS; native class/style remain on the root and take precedence | { root?, cover? } | — |

### Slots

status receives { status, locale, refresh }. It renders complete native content and is read at render time only while nonactive. An existing empty slot suppresses defaults. refresh is a stable emit action regardless of listener presence.

```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 has no payload. @refresh, onRefresh, dynamic listeners and .once follow Vue semantics. There is no v-model.

nativeElement is HTMLDivElement or null. Status changes retain the root and same-mode graphic; nonactive states retain native status editors. Changing canvas/SVG replaces only the graphic. Hidden/unmounted roots are null.

### Provider and styling

components.qrcode supports className, style, classNames and styles. Current locale.QRCode supplies default status labels and the slot scope.

QRCodeCoverBackgroundColor is the single Component Token, derived from current colorBgContainer at 96% opacity. Override it through theme.components.QRCode or the higher-priority root CSS variable --apollo-qrcode-cover-background-color. Dark and compact themes affect the UI and cover; default QR images retain neutral contrast. Callers own contrast when supplying explicit backgrounds/foregrounds.

Native string, array and object styles target the root. Graphics fill its inner area while preserving aspect ratio. size controls logical drawing and DPR controls canvas resolution; root dimensions are not copied as graphic inline styles.

The licensed Nayuki engine and existing matrix/path/correction/icon algorithms are retained. Inputs remain subject to standard QR capacity limits; canvas export follows browser cross-origin security rules. This component adds no download, scanner or request API.


## Basic (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 & Size (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)

The caller controls status. Each @refresh restarts loading and expires again; timers are disposed on unmount. #status receives { status, locale, refresh } and keeps complete native content. An existing empty slot suppresses defaults; active does not consume the slot.

### 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>
```

## Live Cover Token (component-token)

QRCodeCoverBackgroundColor styles the actual cover. Removing and restoring the local theme preserves native status content and its editor. A root CSS variable takes precedence.

### 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


Select one scalar option with RadioGroup / Radio.Group. Use RadioButton / Radio.Button or Group optionType="button" for button presentation.

## API

### Radio / RadioButton

| Property | Description | Type | Default |
|---|---|---|---|
| checked / defaultChecked | Controlled value / local initial value; supports v-model:checked | boolean | — / false |
| value | Scalar identity within Group; native input value outside Group | string / number / boolean | — |
| disabled | Local value takes precedence over Group and ConfigProvider; explicit false is respected | boolean | — |
| title | Native label title | string | — |
| id / name / tabIndex / required / autoFocus | Input attributes; Group owns name, autoFocus focuses on mount | Native attributes | — |
| prefixCls | DOM prefix; custom prefixes require matching static CSS | string | apollo-radio |
| classNames / styles | root (label), icon and label regions; object or ({ props }) => object | Semantic object/function | — |

The input type is fixed to radio. The unused skipGroup, type and standalone optionType declarations have been removed; Group optionType remains.

### RadioGroup

| Property | Description | Type | Default |
|---|---|---|---|
| value / defaultValue | Controlled value / local initial scalar; supports v-model:value | RadioValue (string / number / boolean) | — |
| options | Nonempty options take priority over the default slot | (string / number / RadioOptionItem)[] | [] |
| disabled | Group disabled state; an explicit option disabled value takes precedence | boolean | — |
| name | Native name shared by all child inputs; omitted names are unique per Group | string | Generated |
| optionType | Dot / button presentation; explicit RadioButton retains its presentation | default / button | default |
| buttonStyle | Button fill | outline / solid | outline |
| size | Shared SizeType; medium and middle are the default size | small / medium / middle / large | Current Provider size |
| orientation / vertical | Layout direction; orientation takes precedence | horizontal / vertical; boolean | Horizontal |
| block | Fill the container | boolean | false |
| id / role / prefixCls | Root attributes and prefix | string | — / radiogroup / apollo-radio |

RadioOptionItem retains label, scalar value, style, className, disabled, title, id and required. Its onChange(event, checked) receives the native Radio notification. Numbers, strings and booleans retain their distinct identities.

### Emits

| Component | Event | Payload |
|---|---|---|
| Radio / Button | update:checked | checked: boolean |
| Radio / Button | change | event: Event, checked: boolean (requested snapshot) |
| Radio / Button | click / mouseenter / mouseleave | Native MouseEvent; hover targets label, click fires once |
| Radio / Button | focus / blur | Native input FocusEvent |
| Radio / Button | keydown / keypress | Native input KeyboardEvent |
| Group | update:value | value: RadioValue |
| Group | change | value: RadioValue, event: Event; only when the value changes |
| Group | mouseenter / mouseleave | Native root MouseEvent |
| Group | focus / blur | Native FocusEvent from the root or descendants |

Notifications use Vue emits. RadioChangeEvent is an Event alias with no synthetic target or nativeEvent wrapper. Radio supports @change.stop. Group change has a business value first; use its second event argument to stop native propagation. In h(), use onKeydown / onMouseenter; templates use @keydown / @mouseenter.

Controlled updates are proposals. Rejection restores the accepted DOM state, including siblings automatically unchecked by native Group activation. Releasing control retains the last accepted value. Input, wrapper and semantic props.checked share that state.

### Slots, attrs and references

Radio / Button default slots accept text, 0, arrays, Fragments and Vue nodes. Empty values, booleans and comments do not create an empty label region. Group default slots contain custom Radio / Button controls; nonempty options take priority.

Radio / Button class and native StyleValue target the outer label; other native attrs target input, while title targets label. Group attrs, class, style and native listeners target its div. Business props stay off the DOM. Native capture listeners coexist with owned focus notifications.

| Reference | Exposed members |
|---|---|
| Radio / Button | focus(options?), blur(), input: HTMLInputElement or null; nativeElement: HTMLElement or null (icon span) |
| Group | nativeElement: HTMLDivElement or null |

These are actual Vue template references; handles are null before mount and after teardown. Button forwards the actual Radio handle and notifications.

Native Tab, Space and arrow keys handle navigation/selection and skip disabled options. Native keydown cancellation remains effective. Surviving keyed options retain focus through reorder; removed controls do not reclaim focus. Use separate Groups for independent choices; generated names do not interfere.

## Provider and tokens

Current ConfigProvider.components.radio className/style/classNames/styles merge with local semantic styles and native root style. Direction, disabled state, size and configuration replacement/withdrawal remain reactive.

Current theme tokens, algorithms and theme.components.Radio project to variables on actual Group and Radio/Button roots. All sixteen tokens are consumed by static CSS. radioSize / dotSize remain unitless; numeric spacing becomes px. Current wireframe derives dotSize, radioColor and radioBgColor. Withdrawal restores current defaults.

| Token | Description | Default |
|---|---|---|
| radioSize | Radio size | `16` (unitless) |
| dotSize | Dot size | `6` (unitless) |
| dotColorDisabled | Disabled dot color | `colorTextDisabled` |
| buttonSolidCheckedColor | Text color of checked solid button | `colorTextLightSolid` |
| buttonSolidCheckedBg | Background of checked solid button | `colorPrimary` |
| buttonSolidCheckedHoverBg | Hover background of checked solid button | `colorPrimaryHover` |
| buttonSolidCheckedActiveBg | Active background of checked solid button | `colorPrimaryActive` |
| buttonBg | Button background | `colorBgContainer` |
| buttonCheckedBg | Checked button background | `colorBgContainer` |
| buttonColor | Button text color | `colorText` |
| buttonCheckedBgDisabled | Checked + disabled button background | `controlItemBgActiveDisabled` |
| buttonCheckedColorDisabled | Checked + disabled button text color | `colorTextDisabled` |
| buttonPaddingInline | Horizontal padding of button | `padding - lineWidth` |
| wrapperMarginInlineEnd | Margin right of Radio button | `marginXS` |
| radioColor | Dot color (wireframe branch) | `colorWhite` |
| radioBgColor | Checked background (wireframe branch) | `colorPrimary` |


Static CSS retains fallback values. Native root --apollo-radio-* overrides have final priority. Custom prefixCls changes DOM and component variable names; it does not generate CSS selectors at runtime.


## Basic (basic)

最简单的用法：单独使用时受控 / 非受控均可。

### basic.vue

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

<template>
  <Radio>Radio</Radio>
</template>
```

## Disabled (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>
```

## Radio Group (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>
```

## Radio Group with 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>
```

## Radio Group more (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>
```

## Radio Group with 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>
```

## Radio Group 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>
```

## Radio Button (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>
```

## Solid Radio Button (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)

`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>
```

## Semantic styles (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>
```

## With 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>
```

## Component 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 (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


Rate component.

## When To Use

- Quick rating operation on content.
- Show rating result (with the read-only `disabled` state).

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/rate/demo) for 9 examples.

## API

### Props

| Prop | Description | Type | Default |
|---|---|---|---|
| value | Current value (controlled, `v-model:value`) | `number` | — |
| defaultValue | Default value | `number` | `0` |
| count | Star count | `number` | `5` |
| allowHalf | Allow half star | `boolean` | `false` |
| allowClear | Clear on clicking the same value again | `boolean` | `true` |
| keyboard | Keyboard arrow control | `boolean` | `true` |
| disabled | Read only (merged with DisabledContext) | `boolean` | `false` |
| size | Size | `'large' \| 'middle' \| 'small'` | `'middle'` |
| tooltips | Hint per star (string or TooltipProps object) | `(TooltipProps \| string)[]` | — |
| direction | Text direction (rtl flips half-star/arrow logic) | `'ltr' \| 'rtl'` | `'ltr'` |
| autoFocus | Auto focus after mount | `boolean` | `false` |
| tabIndex | tabIndex of the current star; the root and other stars use `-1` | `number` | `0` |
| id | id of the root `ul` | `string` | — |
| prefixCls | Component class prefix | `string` | `apollo-rate` |

### Events

| Event | Description | Payload |
|---|---|---|
| update:value | Rating update request used by `v-model:value` | `number` |
| change | Rating update request, emitted before `update:value` | `number` |
| hoverChange | Hovered value; `undefined` when leaving | `number \| undefined` |
| focus | Focus enters the rating group | `FocusEvent` |
| blur | Focus leaves the group; moving between stars does not repeat this event | `FocusEvent` |

Component events support Vue's `.once` modifier. Native listeners such as `@keydown` / `@mouseleave`, `class` / `style`, `aria-label`, `aria-labelledby` and `data-*` target the root `ul`. Keyboard handling processes the rating before notifying native listeners; disabled ratings suppress both. Existing `onKeyDown` / `onMouseLeave` spellings use the same native event channel.

With controlled `value`, the displayed rating remains unchanged until the parent accepts an update. Removing `value` retains the last accepted value. `defaultValue` only initializes uncontrolled state. Hover changes the preview and `#character.value`, leaving the selected radio and model unchanged.

The root is a `radiogroup`; provide `aria-label` or `aria-labelledby`. Only the current star is in the Tab order, or the first star when the rating is `0`. A half rating selects the next whole-star item and announces its actual value. Left/right arrow keys update the rating and move focus, with reversed direction in RTL. Enter/Space selects the focused star; `allowClear` clears a repeated selection. Disabled stars leave the Tab order.

### Slots

| Slot | Description | Props |
|---|---|---|
| #character | Custom star character (default StarFilled) | `{ index, value, allowHalf, disabled, count, focused }` |
| #characterRender | Wrap the whole star node (tooltips wrapping composes inside) | `{ node, index }` |

> ⚠️ C8-R2: antd's `character` (ReactNode) and `characterRender` (fn) are **slots only**
> in this library. `tooltips` is a data prop (string / TooltipProps object) and stays.

### Expose

| Method | Description |
|---|---|
| focus() | Focus the current star (no-op when disabled) |
| blur() | Blur the actual focused element in the group (no-op when disabled) |

### Development migration

`change`, `hoverChange`, `focus` and `blur` are declared Vue emits. Existing listeners such as `@change` / `onChange` continue to work. `focus` / `blur` now carry a native `FocusEvent`; focus methods and `tabIndex` target the current radio instead of the root container. `#character.value` follows the visual preview. Adding or removing tooltips preserves star DOM and focus.

### Component Token

Override the six tokens with ConfigProvider's `theme.components.Rate`. Nested providers inherit individual fields. Replacing or removing overrides restores values derived from the current global theme. A custom `prefixCls` uses the matching component variable names.

| Token | Description | Default |
|---|---|---|
| starColor | Selected star color | `yellow6` |
| starBg | Unselected star color | `colorFillContent` |
| starSize | Standard star size | `controlHeight × 0.625` |
| starSizeSM | Small star size | `controlHeightSM × 0.625` |
| starSizeLG | Large star size | `controlHeightLG × 0.625` |
| starHoverScale | Hover and keyboard focus scale | `scale(1.1)` |

Numeric sizes use pixels; theme overrides also accept CSS length strings. Styles apply in this order: theme tokens, `components.rate.style`, then native component `style`. Without an active source theme, static CSS variables retain ownership.

## Design notes

- **Vue-native rebuild of the rc-rate 1.0.1 core** (Rate + Star + util.getOffsetLeft).
- **cleanedValue**: after an allowClear reset the cleared value is remembered; the hover
  guard `nextHoverValue !== cleanedValue` prevents flicker when hovering the same value.
- **tooltips × characterRender composition**: in antd a user characterRender **overrides**
  the tooltip wrapping (JSX spread order); here slots compose (Tooltip inside, user slot
  outside).


## basic (basic)

Focus the rating and use the arrow keys to update its value. `@keydown` receives each native keyboard event once alongside `v-model:value`. Disabled ratings suppress keyboard handling.

### 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)

Customize the star character via the `#character` slot (VNode or text).

### 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)

Per-star custom rendering via the scoped `#character` slot (successor of antd's
`character({ index })` function).

### 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)

Clicking the same value again clears it (`allowClear` defaults to 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)

Override all six Rate component tokens with ConfigProvider's `theme.components.Rate`: the three sizes, selected and unselected colors, and hover scale.

### 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)

Read only, cannot interact.

### 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)

Support selecting half star (`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` adds a hint per star (string or TooltipProps object); controlled via `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


Present operation results, explanations and next actions. Use an appropriately ranked heading in `#title` when the content needs heading semantics.

## When To Use

Use for complex feedback with a title, description, body or actions.

## Examples

Ten real demos cover ordinary statuses, the three exception illustrations, complete custom icons, all semantic parts and live component tokens.

## API

| Prop | Description | Type | Default |
|---|---|---|---|
| status | Ordinary status or exception code; numeric/string codes are equivalent | `'success' \| 'error' \| 'info' \| 'warning' \| 403 \| 404 \| 500 \| '403' \| '404' \| '500'` | `'info'` |
| icon | Default graphic switch: false/null hides it, true/omitted shows it; an existing icon slot takes priority | `boolean \| null` | — |
| title / subTitle | Text fallback for the corresponding slot | `string` | — |
| prefixCls | Current class prefix; applications supply CSS for arbitrary custom prefixes | `string` | Provider prefix |
| classNames | Six semantic classes or a factory reading current props | `ResultSemanticClassNames \| ((info: { props: ResultProps }) => ResultSemanticClassNames)` | — |
| styles | Six semantic styles or a factory reading current props | `ResultSemanticStyles \| ((info: { props: ResultProps }) => ResultSemanticStyles)` | — |

### Slots

| Slot | Content |
|---|---|
| icon | Complete custom content for every status, including native interactive content |
| title / subTitle | Complete title/description content, overriding the matching text prop |
| extra | Actions |
| default | Body |

All five slots take no arguments. Multiple nodes, fragments, comments and native controls remain intact. A present empty slot suppresses fallback and creates no empty container; removing the slot restores fallback. Zero is valid text. Status/theme changes retain content that remains mounted; conditional removal follows Vue's normal unmount behavior.

### Native attributes, events and refs

Native class, all three Vue style forms, id, aria/data, tabindex and listeners belong to the root div. Classes concatenate; local semantic styles override Provider configuration; native root style wins last. There are no business emits or v-models. Root `@click` receives one native event.

`ResultRef.nativeElement: HTMLElement | null` identifies the root and becomes null after unmount. Result does not move focus or create alert/live announcements. Callers can supply native roles and ARIA attributes.

### Provider, semantic parts and themes

`components.result` accepts current className/style/classNames/styles; replacement, removal and restoration take effect. Configuration className/style remain valid root configuration fields. Nearest Providers, direction and prefix updates remain reactive. The six parts are root/title/subTitle/body/extra/icon; semantic factories receive current effective props, including default status info.

Configure `theme.components.Result`, or override root CSS variables. Source aliases and default/dark/compact/combined algorithms update live and remain scoped.

| Token | Type | Default | CSS variable |
|---|---|---|---|
| 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` |

Numeric font sizes use px; zero is valid. Negative/nonfinite numbers and empty strings fall back to current aliases. Strings accept valid CSS lengths, variables or calc expressions. extraMargin uses CSS margin shorthand. Import `@apollo-design/ui/style.css` or `@apollo-design/ui/result/style.css`.

### Static exports and SSR

PRESENTED_IMAGE_403/404/500 are reusable illustration components identical to their ExceptionMap entries; IconMap holds the four ordinary statuses. Default exception illustrations are decorative; ordinary status icons retain their image names. Custom slot content remains accessible. Illustration paths/colors stay static. Direct illustration consumers can supply native SVG names.

Production SSR uses no browser globals; hydrate with matching configuration/content. Types and exports are available from `@apollo-design/ui` or `@apollo-design/ui/result`. See the [development migration](https://github.com/apollocmh/apollo-design-ui/blob/master/docs/migrations/result-contracts.md); no compatibility layer preserves the faulty shapes.


## Success (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)

默认 `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)

警告的结果。

### 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 (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 and complete content (custom-icon)

The complete `#icon` slot overrides the default graphic for every status. Status changes preserve the editor. An empty slot suppresses the fallback; removing the slot restores it.

### 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>
```

## Semantic classNames and styles (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>
```

## Component Token (component-token)

Configure all four tokens through the current source theme. Removing/restoring configuration preserves native editors. Root `--apollo-result-*` variables override component tokens; removing them restores the current theme.

### 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

Display multiple options and allow users to select a single one.

## When To Use

- Display multiple options and user selects a single option;
- When toggling a switch to show different contents.

## Examples





























## API

### SegmentedProps

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| block | Fit width to parent's width | boolean | false |
| disabled | Disable all items | boolean | false |
| options | Set the options | `SegmentedOptions` | [] |
| shape | Set the shape | `'default' \| 'round'` | 'default' |
| size | Set the size | `'small' \| 'middle' \| 'medium' \| 'large'` | 'middle' |
| value | Controlled value | SegmentedValue | - |
| defaultValue | Initial value; falls back to the first option | SegmentedValue | - |
| name | Native `name` of the inner radio inputs | string | auto-generated |
| vertical | Vertical layout (legacy) | boolean | false |
| orientation | Orientation (new API) | `'horizontal' \| 'vertical'` | - |
| classNames | Semantic class names (function supported) | `{ root, icon, label, item }` | - |
| styles | Semantic styles (function supported) | `{ root, icon, label, item }` | - |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:value | Value changed (for `v-model:value`) | `(value: SegmentedValue) => void` |
| change | Propose a changed value | `(value: SegmentedValue) => void` |
| keydown | Native keyboard event before navigation; supports `preventDefault()` | `(event: KeyboardEvent) => void` |

Both value notifications are Vue events. Use `@change` / `v-model:value` in templates and `onChange` / `onUpdate:value` with `h()`; listeners are no longer called manually through attrs.

A controlled parent may reject a request: the actual radio checked state is restored. Releasing control retains the last accepted value. Initialization uses `defaultValue`, or the first option when options first become available. Later reordering/removal does not silently change it; a missing accepted value leaves every option unchecked.

Native class, complete style (objects, strings or arrays), id, ARIA/data and listeners land on the real root div. Native style overrides semantic root style. The root adds no default Tab stop; the enabled selected radio, or first enabled radio, is the single entry. Arrows wrap enabled items; horizontal RTL reverses left/right. Native cancellation and composition suppress navigation. Keyboard focus moves only after the parent accepts the requested value.

Current ConfigProvider disabled, size, direction and `components.segmented` semantic configuration remain reactive, including removal; explicit `disabled=false` overrides global disabled.

### SegmentedOptions

Options accept scalar values or `{ value, label?, icon?, disabled?, title?, className?, id?, tooltip? }`. Data label/icon use complete Vue `VNodeChild`, including zero, arrays and Fragments; render callbacks are unsupported. A label is required without an icon. The options array may be readonly. Option id lands on its label; the native radio submits the string form of the value while events preserve the original scalar type. Icon-only items use title or value as their accessible name; supply meaningful titles.

### Ref

```ts
interface SegmentedRef { nativeElement: HTMLDivElement | null }
```

### SegmentedValue

```ts
type SegmentedValue = string | number;
```

## Theme Variables

| Token | Description | Default |
| --- | --- | --- |
| itemColor | Text color of item | colorTextLabel |
| itemHoverColor | Text color when hover | colorText |
| itemHoverBg | Background when hover | colorFillSecondary |
| itemActiveBg | Background when active | colorFill |
| itemSelectedBg | Background when selected | colorBgElevated |
| itemSelectedColor | Text color when selected | colorText |
| trackPadding | Padding of container | lineWidthBold |
| trackBg | Background of container | colorBgLayout |

`trackPadding` accepts a number (px) or CSS length string; the other seven tokens accept CSS strings. All eight `theme.components.Segmented` overrides reach the real root and respond to replacement/removal.


## Basic (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 (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` 属性使其适配父元素宽度。

### 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` 支持「整组禁用」与「单项禁用」两种粒度。

### 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 (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-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 (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>
```

## Custom render & 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>
```

## Round shape (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>
```

## Sizes (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)

`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>
```

## Semantic 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>
```

## Component 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 Synced (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>
```

## Consistent Height (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


Select component to select a value from options.

## When To Use

- Pick one mutually-exclusive option (single) or several (multiple / tags).
- Use Select instead of Radio when there are more than 7 options or when filtering is needed.
- Large option sets (1000+) are virtualized by default.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/select/demo) (native Vue demos including the three models, live conditional options, filtering and keyboard interaction).

## Conditional options

Default-slot `SelectOption` / `SelectOptGroup` nodes are normalized during rendering, supporting conditional slots, `v-if`, `v-for` and reactive values/labels/disabled state. Explicit `options` take precedence, including `options=[]`; use `undefined` to restore the slot channel. A temporarily removed selected option keeps its cached label and refreshes when it returns. No component key/remount is required; the input and selection state persist.

## API

### Props

| Prop | Description | Type | Default |
|---|---|---|---|
| value / defaultValue | Controlled value (`v-model:value`) / initial value | `SelectValue` | — |
| searchValue | Controlled search text (`v-model:search-value`) | `string` | `''` |
| mode | Mode | `'multiple' \| 'tags'` | single |
| options | Option data (nested groups supported) | `DefaultOptionType[]` | — |
| labelInValue | `change/select/deselect` receive `{ label, value }` | `boolean` | `false` |
| showSearch | Searchable; object form configures filtering | `boolean \| SearchConfig` | `false` |
| filterOption | Custom filter (⚠️ defaults to matching by `value`, case-insensitive) | `boolean \| fn` | — |
| optionFilterProp | Filter fields (array for multi-field OR) | `string \| string[]` | `'value'` |
| filterSort | Sort the filtered options | `fn` | — |
| allowClear | Clear button (`{ clearIcon, label }` to customize) | `boolean \| object` | `false` |
| placeholder | Placeholder text (rich content via the `#placeholder` slot) | `string` | — |
| size | Size (= `SizeType`, includes `medium`) | `'small' \| 'medium' \| 'middle' \| 'large'` | `'middle'` |
| variant | Variant | `'outlined' \| 'filled' \| 'borderless' \| 'underlined'` | `'outlined'` |
| status | Validation status | `'error' \| 'warning' \| 'success' \| 'validating'` | — |
| disabled / loading | Disabled / loading | `boolean` | `false` |
| maxCount | Max selected count (multiple / tags only) | `number` | — |
| maxTagCount / maxTagTextLength | Tag collapsing / text truncation | `number` | — |
| tokenSeparators | Token separators (array or function) | `string[] \| fn` | — |
| listHeight / listItemHeight | List max height / estimated item height | `number` | `256 / 32` |
| popupMatchSelectWidth | Popup width follows the trigger | `boolean \| number` | `true` |
| placement | Popup placement | 4 values | `'bottomLeft'` |
| open / defaultOpen | Controlled open (`v-model:open`) | `boolean` | `false` |
| fieldNames / optionLabelProp | Field mapping / backfill field | — | `label` |
| virtual | Virtual scrolling | `boolean` | `true` |
| classNames / styles | Semantic `root/prefix/suffix/input/placeholder/content/item/itemContent/itemRemove/clear/popup.{root,list,listItem}` | — | — |
| dropdownClassName / dropdownStyle / dropdownMatchSelectWidth / popupClassName / bordered / showArrow etc. | ⚠️ Deprecated | — | — |

Search configuration contains `filterOption`, `filterSort`, `optionFilterProp` and `autoClearSearchValue`. Use `@search` for notifications and `#searchIcon` for content. Filter, sort, tokenization and popup-container functions retain their business roles. `showSearch.onSearch/searchValue/searchIcon` are no longer configuration channels.

Controlled `value`, `searchValue` and `open` updates are proposals. A rejected proposal keeps the accepted value; releasing control retains the last accepted value. `defaultValue/defaultOpen` initialize local state. With `labelInValue`, single-item events receive `{ value, label }`; otherwise they receive `string | number`.

### Events

| Event | Description | Arguments |
|---|---|---|
| change | Value changed (emitted together with `update:value`) | `(value, option)` |
| select / deselect | An option selected / deselected | `(value, option)` |
| search | Search notification from input | `(value: string)` |
| update:searchValue | Search model proposal, including clearing after selection | `(value: string)` |
| openChange / update:open | Open notification / model proposal | `(open: boolean)` |
| focus / blur | Focus | `(event)` |
| clear | Clear clicked | — |
| popupScroll | Dropdown scrolled | `(event: Event)` |
| inputKeyDown | Search input key | `(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` children form, deprecated but supported).

> ⚠️ antd's ReactNode props (`suffixIcon` / `notFoundContent` / `optionRender` /
> `maxTagPlaceholder` etc.) are **scoped slots only** in this library — no same-named
> props are kept (rule C8-R2).

Slots are read during rendering and update when added, replaced or removed. An empty slot intentionally hides content; numeric `0` remains visible. `#loadingIcon/#searchIcon` take priority in their corresponding state; `#suffixIcon` controls other suffix content and receives actual focus. Labels and icon values inside option/configuration data retain their data role; top-level content functions use slots.

### Attrs, Provider and theme

Native `class/style` target the selector root. `id/tabindex/role/aria-*` target the actual input; `data-*` and remaining native attrs target the root. Native listeners merge with internal interaction. `focus/blur` describe component focus. Style precedence is current theme → Provider `style` → Provider/local `styles.root` → native `style`; semantic classes concatenate.

Current, nested and removed ConfigProvider values update reactively. Select Tokens accompany both the root and teleported popup; virtual row estimates follow `optionHeight`. Set a numeric `listItemHeight` when row heights use complex CSS expressions. `SelectPurePanel` shares Props, Slots, Emits and Ref, rendering its open popup in its own layout container.

### Methods

| Method | Description | Arguments | Returns |
|---|---|---|---|
| focus | Focus | `(options?: FocusOptions)` | — |
| blur | Blur | — | — |
| scrollTo | Scroll to a coordinate or option | `(scrollTop \| { index, align, key })` | — |
| nativeElement | Root element | — | `HTMLElement` |

## Design notes

- **Vue-native rebuild of the rc-select 1.10.1 core** (engine/, five layers); no
  `-selector` wrapper in the v6 DOM.
- Known differences from antd are listed in the component README.
- ⚠️ Filtering matches by `value` by default — pass
  `showSearch: { optionFilterProp: 'label' }` to match by label.


## Conditional and dynamic options (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`: a comma splits the input into tags.

### 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 single select.

### 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)

10,000 options with virtual scrolling enabled by default.

### 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)

Debug case: clear button with a custom suffix.

### 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)

Bind the selection, search text and popup with `v-model:value`, `v-model:search-value` and `v-model:open`. Named slots receive the current open and focus state.

### 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)

Override Select Component Tokens via ConfigProvider.

### 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)

Two linked selects for coordinates (the antd original uses hooks; replaced by 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)

Append an Apollo button with `#popupRender`. Clicking it adds an option while preserving the search input focus.

### 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)

Customize the selected value rendering with `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)

Customize multiple tags via the `tagRender` scoped slot.

### 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` accepts a function for custom splitting.

### 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 case: clear combined with search.

### 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 case: flip when there is not enough space.

### 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)

Debug case: the `filled` variant.

### 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)

Hide selected options via a custom `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` receives `{ 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` limits the selection to 2 items (multiple / tags only).

### 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)

Multiple selection, `value` is an array.

### 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)

Groups via nested `options` (the `Select.OptGroup` children form works too).

### 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)

Center-aligned option content.

### 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)

Customize option content via the `optionRender` scoped slot.

### 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)

Four popup placements.

### 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)

Debug case: controlled open.

### 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)

The static panel (`Select._InternalPanelDoNotUseOrYouWillBeFired` equivalent).

### 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)

Overflowed tags collapse into `+N ...` (the antd original uses `maxTagCount="responsive"`; see 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)

Search box: `showSearch` filtering by `label` (the default matches by `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)

Custom filter function via `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)

Pass an array to `optionFilterProp` for multi-field OR matching.

### 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)

Sort the filtered options with `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)

Selected user list (the antd original uses hooks; replaced by 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)

Three sizes: `small`, `middle` and `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)

Validation status: `error` and `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)

Semantic `classNames` and `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)

Custom suffix icon.

### 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 mode, press enter to create a new tag.

### 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)

Four variants: `outlined`, `filled`, `borderless` and `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

Display a placeholder matching the expected content structure. The caller owns loading; Skeleton does not fetch data or finish loading automatically.

## Examples

All eight original demos remain, plus a live component-token example with native variable overrides and a persistent editor.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Skeleton } from '@apollo-design/ui';
const loading = ref(true);
const draft = ref('Persistent data');
</script>
<template>
  <button type="button" @click="loading = !loading">Toggle loading</button>
  <Skeleton :loading="loading" avatar>
    <input v-model="draft" aria-label="Business draft" />
  </Skeleton>
</template>
```

## API

### Skeleton Props

| Property | Behavior | Type | Default |
|---|---|---|---|
| active | Shimmer; respects reduced motion and source motion:false | boolean | false |
| loading | Only false shows content; omitted/undefined show placeholders | boolean | — |
| prefixCls | Current class prefix | string | apollo-skeleton |
| avatar | Avatar block and single-element configuration | boolean / SkeletonAvatarProps | false |
| title | Title block configuration | boolean / SkeletonTitleProps | true |
| paragraph | Paragraph block configuration | boolean / SkeletonParagraphProps | true |
| round | Capsule title and paragraph lines | boolean | false |
| classNames | Six semantic targets; functions receive current `{ props }` | SkeletonSemanticValue&lt;SkeletonSemanticClassNames&gt; | — |
| styles | Six semantic targets; functions receive current `{ props }` | SkeletonSemanticValue&lt;SkeletonSemanticStyles&gt; | — |

### Standalone child props

Named SkeletonAvatar/SkeletonButton/SkeletonInput/SkeletonImage/SkeletonNode exports are identical to Skeleton.Avatar/Button/Input/Image/Node.

| Property | Components | Behavior |
|---|---|---|
| prefixCls | All | Current prefix |
| active | All | Shimmer, false by default |
| classNames / styles | All | Objects with root (outer div) and content (inner shape/content) |
| size | Avatar | small / medium / middle / large / existing default alias / finite nonnegative pixel number; defaults to Provider componentSize |
| shape | Avatar | circle (default) / square |
| size | Button / Input | small / medium / middle / large / existing default alias; defaults to Provider componentSize |
| shape | Button | circle / square / round / default; omitted means no shape class |
| block | Button / Input | Full-width, false by default |
| internalClassName | Node | Existing content-class override; empty uses the node class; Image uses the image class internally |

The existing size="default" warning remains; prefer medium. Root className aliases were removed. Inner dimensions/styles use styles.content.

### Block configuration

avatar/title/paragraph prefixCls/className/style are configuration data. Classes combine; matching semantic styles override configuration styles.

| Field | Block | Behavior |
|---|---|---|
| size / shape | avatar | Size and circle/square; defaults to large, square when title exists without paragraph, otherwise circle |
| width | title | Pixel number or CSS string; 38% without avatar and with paragraph, 50% with both, otherwise unset |
| rows | paragraph | Three without avatar and with title, otherwise two; nonfinite/negative means zero, positive fractions truncate |
| width | paragraph | Array applies per line; scalar applies to the last line; default last width 61% without avatar or title |

Nonfinite numeric lengths are ignored; zero remains valid. The nested avatar is one shape: use main classNames.avatar/styles.avatar rather than standalone two-layer classNames/styles configuration.

### Native attrs, Provider and priority

All six components route id/data/ARIA/tabindex/native events to their real root. Vue string/array/object class/style work; native styles win. Child content has its own semantic target. Skeleton has no root when loading=false, so attrs are not copied to business slots; add your own persistent host when needed.

The main component consumes current components.skeleton className/style/classNames/styles, including replacement/removal/restoration. Standalone children consume the global prefix, applicable size and source theme; they do not reinterpret the main six-target configuration as their two-target configuration. Nearest Provider scope, instance isolation and live RTL apply. Arbitrary custom prefixes still need matching static CSS.

### Slots, events and models

| Component / default slot | Behavior |
|---|---|
| Skeleton | Complete unwrapped content when loading=false |
| SkeletonNode | Complete native custom content; surrounding style/theme changes retain editors |
| SkeletonImage | An existing slot wins, including intentional emptiness; absent slot uses the original SVG |

No business emits or v-model; the caller controls loading. Native listeners receive DOM events. Main semantic targets are root/header/section/avatar/title/paragraph; children use root/content.

### Expose

Only the main component exposes nativeElement: HTMLDivElement | null. It is null while loading=false and after unmount. Loading switches intentionally unmount business content: keep data in caller-owned reactive state; DOM identity/focus do not survive intentional removal.

### Component tokens

All shapes consume current theme.components.Skeleton and respond to removal/restoration. Current gradient names win over existing aliases, then current Alias defaults. Root native style can override corresponding --apollo-skeleton-* variables.

| Token | Type | Default source |
|---|---|---|
| gradientFromColor | string | colorFillContent |
| gradientToColor | string | colorFill |
| color (existing deprecated alias) | string | gradientFromColor |
| colorGradientEnd (existing deprecated alias) | string | gradientToColor |
| titleHeight | number / CSS length string | controlHeight / 2 |
| blockRadius | number | borderRadiusSM |
| paragraphMarginTop | number | marginLG + marginXXS |
| paragraphLiHeight | number | controlHeight / 2 |

### Accessibility, SSR and styles

The loading root owns aria-busy=true. Decorative header/section blocks are aria-hidden, keeping empty placeholder headings out of the accessible tree. Native attrs may supply a role/name. Node/Image business slots remain accessible; the built-in SVG is decorative. Active animation respects prefers-reduced-motion and source motion:false; no live announcement is added automatically.

SSR does not depend on window; native slots and current source themes render on the server. Exact hydration/browser acceptance is recorded in the complete audit. Import @apollo-design/ui/skeleton/style.css. Development migration details: docs/migrations/skeleton-contracts.md; executed checks, evidence and unverified boundaries: docs/audit/2026-10-27-skeleton-contract-audit.md.


## Basic (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>
```

## With avatar (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 state (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 and round (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 (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>
```

## Live component tokens (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 (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 (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 (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

A slider input for selecting a value or a range of values.

## When To Use

- Selecting one or several numbers within a bounded range.
- Letting users perceive where the current value sits inside the range.
- Needing instant feedback (value updates while dragging).

## Import

```ts
import { Slider } from '@apollo-design/ui';
```

## Examples



























## API

### Slider

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| value（`v-model:value`） | Current scalar/range value; null clears handles | `number \| number[] \| null` | —— |
| defaultValue | Local initial value, including null to clear | `number \| number[] \| null` | —— |
| min | 最小值 | `number` | `0` |
| max | 最大值 | `number` | `100` |
| step | 步长；`null` 表示只按 `marks` 取值 | `number \| null` | `1` |
| range | 双（多）把手；对象形态可开 `editable` / `draggableTrack` / `minCount` / `maxCount` | `boolean \| SliderRangeConfig` | `false` |
| count | Fixed interval count (count + 1 handles); editing bounds are separate | `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` | —— | —— |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| `update:value` | 值变化（`v-model:value`） | `(value: number \| number[])` |
| `change` | 值变化（与 `update:value` 同时发出） | `(value: number \| number[])` |
| `beforeChange` | First effective proposal, once per interaction | `(value: number \| number[])` |
| `changeComplete` | Final proposal when the interaction ends | `(value: number \| number[])` |
| `focus` / `blur` | Native handle focus / blur | `(event: FocusEvent, index: number)` |
| `keydown` / `keyup` | Native keyboard notification; keydown runs before internal actions | `(event: KeyboardEvent, index: number)` |

### Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| `handle` | Real native handle replacement, retaining nodeProps/ref | `{ index, prefixCls, value, dragging, draggingDelete, nodeProps, className, style }` |
| `activeHandle` | Decorative active range anchor, wrapped in the default Tooltip while active | Same complete scope |

### Methods (ref)

| Method | Description |
| --- | --- |
| `focus()` | Focus the first enabled real handle |
| `blur()` | Blur the active element within Slider |

### Keyboard

| Key | Behavior |
| --- | --- |
| ← / → | −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）。

## Design Token

| Token | Default (light) | Description |
| --- | --- | --- |
| `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)` | 禁用时的已选轨道 |

Switch themes through `ConfigProvider`'s `theme`; component styles are static CSS + CSS variables (zero runtime).

## Current native contract

value/defaultValue accept number, number[] or null (clear). Single mode emits a number and range mode emits an array. min/max/step are declared on SliderProps. count is the fixed number of intervals (count + 1 handles); range.minCount/maxCount constrain editing and do not replace that responsibility.

Updates are proposals. Rejection preserves accepted DOM/ARIA state, and withdrawal retains the last accepted value. beforeChange receives the first effective proposal once per interaction; change/update:value follow. changeComplete receives that interaction's final proposal even if the controller refused it. Unchanged keys, bare keyup, IME, native cancellation, touchcancel, invalidated gestures and teardown do not emit fabricated completion.

keydown/keyup are owned native notifications `(event: KeyboardEvent, index: number)`. keydown runs before internal actions and respects preventDefault(). Use onKeydown/onKeyup with h(), or @keydown/@keyup in templates.

handle and activeHandle receive the complete public SliderHandleInfo: required index/value/prefixCls/dragging/draggingDelete/nodeProps/className/style. nodeProps provides native HTML attributes, single native event functions and the actual element ref. Bind it to the real handle to retain focus and keyboard/ARIA behavior. activeHandle receives the actual current index and remains a decorative anchor without a slider role or keyboard events. It is wrapped by the default range Tooltip while hovered, focused or dragged, unless tooltip.open locks presentation.

The existing ref methods remain focus()/blur(); focus selects the first enabled real handle, including a custom slot node. Surviving handles retain identity through mode and Tooltip configuration changes. No nativeElement member is added.

Native class/style, data/title and ordinary listeners target the root. Style accepts Vue strings, objects and arrays. aria-* and native tabindex target actual handles; explicit tabIndex and per-handle ARIA props take precedence, while role and value metadata remain owned by Slider.

tooltip.formatter takes priority over the top-level numeric formatter; null hides tips. Tooltip prefix, placement, semantic options and explicit containers are consumed by Tooltip; its current Provider owns the default container. Slider owns visibility through native focus/hover/drag and tooltip.open. Unsupported tooltip.defaultOpen/trigger/onOpenChange/onUpdate:open and unused internal value/draggingDelete declarations are removed; draggingDelete remains on the actual handle scope.

Current components.slider className/style/classNames/styles, direction and disabled values remain reactive. All eighteen current theme.components.Slider tokens and current theme aliases project to actual root variables, with numeric lengths in px. Native root style has final priority. Custom DOM prefixes require matching static CSS.


## Basic (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>
```

## Marks (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 (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)

`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-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 (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 (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>
```

## Events (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 (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 (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 (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 handles (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>
```

## With input number (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>
```

## Component 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>
```

## Semantic Styles (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


Space separates content. SpaceCompact joins adjacent controls, and SpaceAddon adds a custom cell.

## Examples

The [15 real demos](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/space/demo) cover basic/vertical spacing, sizes, alignment, wrapping, separators, compact controls, horizontal/vertical button groups, nested groups, empty content, row gaps, semantic styles and Alias themes.

## API

### Space

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| prefixCls | Complete DOM class prefix | `string` | ConfigProvider prefix + `-space` |
| size | Gap or `[horizontal, vertical]` gaps | `SpaceSize \| [SpaceSize, SpaceSize]` | Current `components.space.size`, then `'small'` |
| orientation | Layout direction; highest priority | `'horizontal' \| 'vertical'` | `'horizontal'` |
| vertical | Explicit false also overrides legacy direction | `boolean` | — |
| align | Horizontal default is center; vertical omission adds no alignment | `'start' \| 'end' \| 'center' \| 'baseline'` | Horizontal `'center'` |
| separator | Complete Vue content data, including numeric zero | `VNodeChild` | — |
| wrap | Enables flex wrapping; vertical wrapping needs a bounded height | `boolean` | `false` |
| classNames | root/item/separator classes; object or function receiving current `{ props }` | `SpaceSemanticValue<SpaceSemanticClassNames>` | — |
| styles | root/item/separator styles; object or function receiving current `{ props }` | `SpaceSemanticValue<SpaceSemanticStyles>` | — |
| ~~direction~~ | Deprecated; use orientation | `'horizontal' \| 'vertical'` | — |
| ~~split~~ | Deprecated; use separator data or #separator | `VNodeChild` | — |

`SpaceSize = 'small' | 'medium' | 'middle' | 'large' | number`. Presets use the paddingXS/padding/paddingLG Alias tokens. Numeric gaps use px. Zero is a valid zero gap and never falls back to the preset; NaN adds no gap.

| Slot | Description |
| --- | --- |
| default | Current content; each nonempty child has an item host |
| separator | Overrides separator/split data; an intentionally empty slot hides separators |

Slots are read during render and support conditional addition, replacement and removal. Priority is #separator → separator when not undefined → split. Null, booleans, empty strings and comments are empty; zero is content. Separators appear only between content items.

Arrays and Fragments flatten while preserving keyed Fragment scopes. String, number and Symbol keys, theme changes and class/prefix updates retain business child identity. Unkeyed children retain identity by position. A missing/empty child list produces no root. Empty placeholders within a nonempty list can retain the root without item hosts.

### SpaceCompact

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| prefixCls | Complete DOM class prefix | `string` | Provider prefix + `-space-compact` |
| size | Size passed to child controls | `SizeType` | Current ConfigProvider.componentSize |
| orientation | Layout direction | `'horizontal' \| 'vertical'` | `'horizontal'` |
| vertical | Explicit boolean direction, below orientation | `boolean` | — |
| block | Fills the parent width | `boolean` | `false` |
| ~~direction~~ | Deprecated; use orientation | `'horizontal' \| 'vertical'` | — |

The default slot contains real compact controls; no child DOM wrapper is added. Null, booleans, comments and empty text do not occupy edge positions; zero remains content. Nested first/last boundaries are combined with the outer group. Controls consume compactSize, compactDirection, isFirstItem and isLastItem using their own prefix. Where size is supported, a local size wins over current compactSize, then the Provider size.

`useCompactItemContext(prefixCls, direction)` returns three ComputedRefs: compactSize, compactDirection and compactItemClassnames. Horizontal classes use `-compact-item/first-item/last-item`; vertical classes use `-compact-vertical-*`; RTL adds the corresponding item-rtl class. NoCompactStyle provides null to isolate its subtree; siblings remain unaffected and isolated controls use their own/Provider configuration.

### SpaceAddon

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| prefixCls | Complete DOM class prefix | `string` | Provider prefix + `-space-addon` |
| variant | Cell appearance | `'outlined' \| 'filled' \| 'borderless' \| 'underlined'` | `'outlined'` |
| disabled | Decorative disabled cell state; child controls manage their own disabled state | `boolean` | `false` |
| status | Validation appearance | `'error' \| 'warning' \| 'success' \| 'validating' \| ''` | — |

The default slot accepts complete Vue content. Current compact size and boundaries control the cell. Outlined/filled horizontal/vertical/RTL groups retain outer corners; a singleton retains all four corners. Underlined has a transparent background, zero radius and only a bottom border using the current lineWidth/lineType. Borderless has no border. Error/warning text equally blends the existing colorErrorText/colorWarningText and current colorText Alias; outlined borders and underlined bottom borders retain status colors. Disabled text overrides status text while retaining the bottom border and status border color; filled + disabled restores the disabled background. Success/validating retain status classes without adding paint changes.

### Native attrs, refs and configuration

All three components route native class/style/listeners/data/ARIA attrs to their root div. Native style accepts Vue objects, strings and arrays. There are no business emits or v-models, and no implicit list/form roles. Actual buttons and inputs own interaction semantics.

Each ref exposes only `nativeElement: HTMLDivElement | null`. It is null before mounting and while Space/Compact have no content. Addon always has a root.

Configure Space with `ConfigProvider :components="{ space: { size, className, style, classNames, styles } }"`. Replacement/removal takes effect immediately. Classes concatenate. Style priority is Provider semantic → Provider root style → local semantic → native attrs. Semantic functions receive current merged size/orientation/align.

### Themes and exports

Space, Compact and Addon define no component tokens; prepareSpaceComponentToken returns `{}`. Existing Alias tokens control gaps, font, borders, radii and Addon paint. Current aliases support ConfigProvider, ThemeProvider, nested scopes and SSR. Root native style variables have the final priority.

```ts
import { Space, SpaceCompact, SpaceAddon } from '@apollo-design/ui';
import '@apollo-design/theme/tokens.css';
import '@apollo-design/ui/space/style.css';
```

Real Button/Input/Select controls also require their CSS; alternatively import `@apollo-design/ui/style.css`.

Static aliases Space.Compact/Space.Addon and separate ASpace/ASpaceCompact/ASpaceAddon install names remain. Public component/ref/size/config/semantic types and existing context/helper exports are retained.

prefixCls changes DOM names; arbitrary prefix CSS is not generated at runtime. `genSpaceStyle('brand')` creates static `.brand-space`, `.brand-space-compact` and `.brand-space-addon` rules. Provider prefixes should match pre-generated CSS. Default output uses apollo.

See the [migration record](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/space-contracts.md) for behavior changes and prior syntax.


## Basic (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 (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 (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 (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 (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)

通过 `#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 Mode (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-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 (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>
```

## Nested Compact (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 (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 (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-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 (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>
```

## Component 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 {#when-to-use}

Show the state of an asynchronous operation. Callers provide spinning; a positive delay prevents brief loading flashes and closing is immediate.

## Examples {#examples}


## API

Native class, style, DOM events and ARIA attributes target the content root and update normally. Spin declares no business emits or v-model.

| Property | Description | Type | Default |
|---|---|---|---|
| spinning | Target loading state | boolean | true |
| delay | Positive finite milliseconds before showing; other values do not delay | number | 0 |
| size | Indicator size; middle/default use medium, with the existing default warning | 'small' \| 'medium' \| 'middle' \| 'large' \| 'default' | 'medium' |
| description | Content; an existing #description slot takes precedence, including zero | VNodeChild | - |
| fullscreen | Fixed fullscreen cover, preserving the content host and nodes | boolean | false |
| percent | Omitted means indeterminate; explicit numbers including zero render a ring clamped to 0–100; auto estimates every 200ms; nonfinite values are indeterminate | number \| 'auto' | - |
| prefixCls | Current class prefix; load matching prebuilt CSS | string | 'apollo-spin' |
| classNames | Per-slot classes concatenate Provider and local values | `SpinSemanticValue<SpinSemanticClassNames>` | - |
| styles | Per-slot shallow merges, local values win; factories receive current merged props | `SpinSemanticValue<SpinSemanticStyles>` | - |
| tip | Existing deprecated description alias | VNodeChild | - |
| wrapperClassName | Existing deprecated wrapper class, used with a default slot or fullscreen | string | - |

### Slots

| Slot | Scope | Behavior |
|---|---|---|
| default | - | Native body content, including conditional registration/removal |
| indicator | { percent: number \| undefined } | Complete Vue content including fragments, multiple nodes and native controls; bind percent explicitly to child components |
| description | - | Content that overrides the prop; empty content creates no wrapper |

An existing named slot wins even when intentionally empty. Inactive loading does not consume indicator/description slots. Indicator scope contains the current number, an estimate for auto, or undefined for indeterminate progress. User VNodes are neither cloned nor given hidden attributes.

### Expose and programmatic configuration

nativeElement is HTMLDivElement or null and identifies the stable content host. ConfigProvider spin settings supply current className/style/classNames/styles/indicator; the programmatic indicator VNode retains its own attributes.

Spin.setDefaultIndicator(indicator: VNodeChild), also exported by name, sets module default content. null/undefined restore the built-in indicator. The command does not schedule updates; mounted instances read it on their next actual render. getDefaultIndicator returns that value. Instance slots take precedence over Provider and module defaults.

## Semantic DOM

| Slot | Actual target |
|---|---|
| root | Stable content div carrying native attrs |
| section | Separate stable loading layer in normal, nested and fullscreen modes |
| indicator | Complete indicator host, including the visible progress ring |
| description | Nonempty description div |
| container | Native default-slot body |
| tip | Existing deprecated description semantic alias |
| mask | Actual fullscreen cover, sharing the section element; hidden and inert while inactive |

Root and section styles target separate elements. Use styles.mask for the fullscreen cover. Descriptions use readable defaults. Built-in animations respect theme.token.motion=false and prefers-reduced-motion; callers own animations in custom content.

## Design Token

All four tokens consume current theme.components.Spin, including updates, removal and restoration. Native root CSS variables take precedence. contentHeight caps the nested loading layer at 400 by default, without forcing body height or limiting fullscreen.

<ComponentTokenTable component="Spin"></ComponentTokenTable>


## Basic (basic)

spinning defaults to true. The built-in four dots indicate indeterminate loading.

### basic.vue

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

<template>
  <Spin />
</template>
```

## Size (size)

The three sizes consume current dotSizeSM, dotSize and dotSizeLG. Nested instances own their sizes.

### 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)

Use description or #description for current content, including zero. An empty existing slot suppresses the prop without creating an empty wrapper. Inactive loading does not consume it.

### 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)

The default slot owns the body. A stable loading layer shares its layout area; busy content dims and ignores pointer input. Empty content still reserves space for the loader.

### 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 (delay-and-debounce)

A positive delay prevents loading flashes; closing is immediate. Configuration changes cancel and restart pending work, and unmount clears timers. Without a positive delay, loading follows the Vue update.

### 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 spinning indicator (custom-indicator)

Render SVG, components, multiple nodes or native controls through #indicator with a { percent } scope. Child attributes remain native, semantic styles target the host, and empty slots suppress defaults.

### 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>
```

## Progress (percent)

Omitted percent is indeterminate. Explicit numbers including zero render a named ring in the first client/server render, with both geometry and value clamped to 0–100. Auto estimates every 200ms and stops on close or unmount.

### 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>
```

## Custom semantic dom styling (style-class)

Root, section, indicator, description, container and mask target their actual hosts; tip is the existing description alias. Object/factory settings consume current values, with local styles taking precedence over 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 (fullscreen)

The actual mask is a fixed fullscreen cover while body and native editors remain in flow. Mode changes preserve section/content identity. styles.mask targets the cover, which is hidden and inert while inactive.

### 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>
```

## Live component tokens (component-token)

Toggle all four component tokens to update the three sizes and maximum nested loading-layer height. Body height and editor identity survive theme removal/restoration. Built-in animations respect motion=false and reduced-motion preferences.

### 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


A splitter container with draggable panels.

## When To Use

- Adjustable multi-pane layouts (IDE panels, detail page columns).
- Panel collapse/expand with size constraints (min/max).

## API

### Splitter

| Prop | Description | Type | Default |
|---|---|---|---|
| orientation | `'horizontal' \| 'vertical'` | — | `'horizontal'` |
| vertical | Same as `orientation="vertical"` | `boolean` | — |
| layout | ⚠️ Deprecated: use `orientation` | — | — |
| collapsible | `{ motion?: boolean; icon?: { start?, end? } }` | — | — |
| lazy | Drag shows a preview line only; commit on release | `boolean` | — |
| destroyOnHidden | Destroy collapsed panel content | `boolean` | — |
| classNames / styles | Current objects or `({ props: SplitterProps }) => object`, with `{ root, panel, dragger }`; dragger supports default/active styles | — | — |

### Events

`resizeStart` / `resize` / `resizeEnd` (sizes: number[]), `collapse`
(collapsed: boolean[], sizes: number[]), `draggerDoubleClick` (index: number).

These are owned Vue emits. Templates naturally use `@resize-start`, `@resize-end` and `@dragger-double-click`; `h()` uses `onResizeStart`, `onResizeEnd` and `onDraggerDoubleClick`. Notifications are no longer runtime callback props and are delivered once. Lazy drag submits one `resize` and one `resizeEnd` on release; cancellation discards its preview.

### Slots

| Name | Description |
|---|---|
| default | Panel content (`<Splitter.Panel>` list) |
| draggerIcon | Custom dragger icon (was the `draggerIcon` prop) |

### Splitter.Panel

`size` / `defaultSize` / `min` / `max` (number px or `'50%'`), `collapsible`
(boolean or `{ start?, end?, showCollapsibleIcon? }`), `resizable`,
`destroyOnHidden`.

### State, native attrs and refs

`size` is controlled: the parent accepts a `resize` proposal by assigning the new values. Rejection preserves the current layout; removing all `size` props continues from the last accepted sizes. Partially controlled layouts allocate the other panels through the existing size algorithm. `defaultSize` only initializes a newly mounted panel. Give dynamic panels stable business keys: size, collapse memory and editor identity follow those keys, and removal releases their state.

Splitter and Panel each forward native `class`, `style`, data/ARIA attrs and DOM listeners to their own actual root. Styles accept Vue strings and arrays; the existing Panel `className` alias and semantic fields remain. Panel default slots render complete text, zero, arrays and conditional content. Collapse retains content unless `destroyOnHidden` is set; Panel can override the container setting.

Both Splitter and actual Panel refs expose `{ nativeElement: HTMLDivElement | null }`, cleared on unmount. The named `SplitterPanel` and compound `Splitter.Panel` belong inside Splitter.

### Keyboard and resources

Resizable separators are Tab stops. Arrow keys along the current axis resize by 10px, or 50px with Shift; Home / End reach the actual min / max bounds. Horizontal RTL mirrors direction. Disabled separators leave the Tab order. Collapse buttons support Enter / Space. Changing the axis, lazy mode, disabled state or panel key order during a drag cancels its pending preview and releases window listeners; unmount also releases ResizeObserver. CSS transitions respect reduced motion.

## Theme (Component Token)

4 tokens: `splitBarSize`(2px), `splitTriggerSize`(6px), `resizeSpinnerSize`(20px),
`splitBarDraggableSize`(20px) — CSS variables `--apollo-splitter-*`.

Set current overrides through `ConfigProvider` theme components: `{ Splitter: { splitBarSize: 4, splitTriggerSize: 12, resizeSpinnerSize: 28 } }`. Replacement, removal and nested themes update actual consumers. `splitBarDraggableSize` inherits `resizeSpinnerSize` unless explicitly set. Native inline CSS variables apply last. Dynamic prefixes update DOM names; custom-prefix styles still need their preloaded static CSS.


## Basic (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 (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)

`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 Panels (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 (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 (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)

`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 (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 (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)

`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


Display numeric values and clocks using native Vue content. Values and targets are supplied by the caller; there is no v-model or built-in numeric animation.

## Examples

All seven examples remain: basic/loading, units, card layout, formatted native values, restartable clocks with live direction, semantic styles and component tokens. The historical animated URL demonstrates formatting, without claiming an animation engine.

## Statistic Props

| Prop | Behavior | Type | Default |
|---|---|---|---|
| prefixCls | Current class prefix; custom prefixes require matching static CSS | `string` | Provider prefix + `-statistic` |
| value | Raw numeric value or literal nonnumeric text | `number \| string` | `0` |
| title / prefix / suffix | Text fallback; an existing slot takes precedence, including an empty slot | `string` | — |
| precision | Truncate/pad decimal digits, negative to zero, fractions toward zero; ignore nonfinite values; no rounding | `number` | Preserve input decimals |
| decimalSeparator | Literal decimal separator | `string` | `'.'` |
| groupSeparator | Literal grouping text, including dollar replacement characters | `string` | `','` |
| loading | Mark root busy and replace/unmount content with a decorative, aria-hidden Skeleton; rebuild when restored | `boolean` | `false` |
| valueStyle | Existing deprecated content style alias; styles.content wins; existing setup-time warning retained | `CSSProperties` | — |
| classNames / styles | Seven semantic targets; object or `({ props }) => object` using current props/Provider | Exported types | — |
| onMouseenter / onMouseleave | Native root mouse listeners, also `@mouseenter`/`@mouseleave` | `(event: MouseEvent) => void` | — |

## Slots

| Slot | Scope | Behavior |
|---|---|---|
| title / prefix / suffix | None | Complete Vue content; intentional empty content suppresses fallback props |
| value | `{ value: number \| string, text: string }` | Raw value and current formatted text; write native template content instead of wrapping internal VNodes |

The value semantic container remains available for class/style, including an empty value slot. Numeric updates, formatting and adjacent slots retain native editors; loading unmounts content.

## Statistic.Timer / StatisticTimer

Share presentation props, title/prefix/suffix slots and all seven semantic targets. Numeric precision/decimalSeparator/groupSeparator are excluded because clock text uses format.

| Prop | Behavior | Type | Default |
|---|---|---|---|
| type | Required, reactive direction | `'countdown' \| 'countup'` | — |
| value | Target timestamp or Date-parseable string; future for countdown, past for countup | `number \| string` | `0` |
| format | Y/M/D/H/m/s/S units, repeated zero padding and `[literal]` escapes; fixed 365-day years / 30-day months | `string` | `'HH:mm:ss'` |

| Event | Payload | Timing |
|---|---|---|
| change | Nonnegative milliseconds, `number` | Immediately after mount and approximately every 1000/60ms; never during SSR or for invalid dates |
| finish | None | Once per completed countdown cycle, after change(0); stops scheduling; target/direction changes start a new cycle |

The Timer value slot receives `{ value, text, duration, type }`. Value is the original target; duration is nonnegative milliseconds or null before mount/for invalid dates, when text is `'-'`. Other slots are forwarded directly.

SSR and hydration start with `'-'`. Effects begin after mounting, read actual Date.now and clean up on unmount. Invalid dates do not schedule or emit; a valid target restarts the clock. Format changes do not restart completed cycles. Background tabs can throttle callbacks; elapsed time is not accumulated from frame counts.

## Statistic.Countdown / StatisticCountdown

The existing fixed-countdown export shares presentation, format, slots, events and the actual root ref; type is injected. Its existing development deprecation notice remains. Named and attached component exports have identical implementations and precise types; no legacy content callbacks are retained.

## Attrs, ref, Provider and tokens

Class/style, id/tabindex, ARIA/data and native listeners target the actual root div. All Vue style forms work. Timer change/finish are business events; input change events do not become duration notifications. All three components expose `nativeElement: HTMLDivElement | null`, cleared on unmount.

Semantic targets: root/header/title/content/value/prefix/suffix. Provider `components.statistic` className/style/classNames/styles follow current replacement/removal; local semantic configuration wins and native attrs styles apply last. Source themes use `theme.components.Statistic`; nearest providers, RTL and neighboring instances remain independent.

| Token | Default | CSS variable |
|---|---|---|
| titleFontSize | Current fontSize, initially 14 | `--apollo-statistic-title-font-size` |
| contentFontSize | Current fontSizeHeading3, initially 24 | `--apollo-statistic-content-font-size` |

Tokens accept finite nonnegative numbers, revert to current aliases when removed and yield to native CSS variables. Theme changes retain native editors. Callers own custom-color contrast and announcement policy; clocks do not enable 60Hz aria-live announcements.


## Basic (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>
```

## Prefix & Suffix (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>
```

## In Card (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>
```

## Formatted value (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 (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>
```

## Semantic styles (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>
```

## Component 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


A navigation bar that guides users through the steps of a task.

## When To Use

- The task is divided into sequential steps.
- Show the user where they are in the process.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/steps/demo) (21 demos, including native scoped slots).

## API

### Props

| Prop | Description | Type | Default |
|---|---|---|---|
| items | Step data (`title/subTitle/content/icon/status/disabled/onClick`; VNodes via programmatic `h()`) | `StepItem[]` | — |
| type | Type | `'default' \| 'navigation' \| 'inline' \| 'panel' \| 'dot'` | `'default'` |
| variant | Variant | `'filled' \| 'outlined'` | `'filled'` |
| size | Size (`default` deprecated ⇒ `medium`) | `'small' \| 'medium' \| 'middle' \| 'default'` | `'middle'` |
| orientation | Orientation | `'horizontal' \| 'vertical'` | `'horizontal'` |
| titlePlacement | Title placement (auto-derived for dot/vertical) | `'horizontal' \| 'vertical'` | `'horizontal'` |
| current | Current step (0-based); supports `v-model:current` | `number` | `0` |
| initial | Start index | `number` | `0` |
| status | Override current step status | `'wait' \| 'process' \| 'finish' \| 'error'` | `'process'` |
| percent | Progress ring percent on the current process step | `number` | — |
| maxCount | Max visible steps (≥3, hidden ranges collapse into ellipsis steps) | `number` | — |
| responsive | Auto switch to vertical on narrow screens | `boolean` | `true` |
| ellipsis / offset | Ellipsis mode / inline offset | `boolean` / `number` | — |
| prefixCls | DOM class prefix; custom prefixes require matching static CSS | `string` | `'apollo-steps'` |
| classNames / styles | Classes/styles for ten semantic regions; functions receive current resolved props | `StepsProps['classNames']` / `StepsProps['styles']` | — |
| direction / labelPlacement / progressDot | ⚠️ Deprecated (`orientation` / `titlePlacement` / `type="dot"`) | — | — |

### Events

| Event | Description | Parameters |
|---|---|---|
| change | Requests a different step; a listener enables click and Enter/Space actions on enabled items | `(current: number)` |
| update:current | Model update request; also enables click and keyboard actions on enabled items | `(current: number)` |

The parent controls current; an event only proposes a change. The active step stays unchanged until the parent updates current. Use `v-model:current` directly or listen to `@change`, including `.once` or listener arrays. Native root change events do not invoke this business event. Root `@click` and the data-item `items.onClick` callback receive MouseEvent; disabled items do not invoke their callback.

### Slots

| Slot | Description | Props |
|---|---|---|
| #iconRender | Custom icon rendering (replaces the default icon node) | `{ iconNode, index, active, item }` |
| #itemRender | Wrap the whole step node | `{ itemNode, index, active, item }` |
| #itemWrapperRender | Wrap the wrapper layer | `{ itemNode }` |
| #progressDot | Custom dot rendering (successor of the deprecated `progressDot` function) | `{ iconNode, index, status, title, description, content }` |

> ⚠️ C8-R2: antd's `iconRender` / `itemRender` / `itemWrapperRender` / `progressDot(fn)`
> are **scoped slots only** in this library. `items` fields (`icon` etc.) are the data
> API — programmatic VNodes via `h()` are fine.

All four slots receive one named object with precise inference in native Vue templates and return VNodeChild. A present empty slot overrides the matching node; removing it restores the default. Items supply data; there is no default content slot, and the unused StepsSlots.default declaration has been removed directly. Inline content has its default Tooltip even without itemRender; custom itemRender can safely render itemNode. See the [native slot notes](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/steps-native-slots.md).

## Design notes

- **Vue-native rebuild of the rc-steps 1.2.3 core** (Steps/Step/StepIcon/Rail +
  the useDisplaySteps collapsing algorithm).
- **maxCount collapsing**: first/last/current always kept; remaining slots filled by
  distance priority; non-contiguous ranges render as disabled ellipsis steps.
- **rail semantics**: the connector's status is **nextStatus** (leading to the next step).
- **Differences**: Wave ripple not implemented (no wave infra), `components` injection
  not wired — see the component README.

## Reactivity

Visible items, folding and active status update with items/current/initial/maxCount; click actions use the current index mapping. Native class/style are read during render and accept Vue string/object/array styles; matching styles.root values retain their existing priority. Documented classNames/styles functions receive current resolved props. Steps has no large variant, so a global large default resolves to medium.

responsive can change from false to true after mount and immediately uses the current viewport, without waiting for a resize. Disabling it restores the explicit/default orientation.

## Theme tokens

`ConfigProvider.theme.components.Steps` consumes nine fields: `descriptionMaxWidth`, `customIconFontSize`, `iconSize`, `iconFontSize`, `dotSize`, `dotCurrentSize`, `navArrowColor`, `navContentMaxWidth` and `iconSizeSM`. Current theme values are scoped to the component root and support replacement, removal and nesting. Deprecated descriptionMaxWidth retains its existing behavior. Explicit native style and styles.root override matching theme variables, with styles.root retaining the final priority. Icon data 0 renders zero; false/empty-string icons intentionally render no content. Omitting icon restores the default number.

Development version `0.0.0` removes the ineffective historical tokens `customIconSize`, `customIconTop`, `iconTop` and `titleLineHeight`. Their settings were never consumed by CSS. Use iconSize/customIconFontSize or existing semantic styles for supported customization. There is no compatibility layer or deprecation period. Vue change emits now owns notification; programmatic `h(Steps, { onChange })` and its numeric payload remain supported. Templates use `@change`.


## clickable (clickable)

Listening to `@change` makes the steps clickable and keyboard-accessible. The parent accepts a request by updating 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)

Override Steps icon size and custom icon font size through ConfigProvider. Steps consumes the current scoped tokens, including later theme replacements.

### 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)

Customize dots via the `#progressDot` scoped slot.

使用原生 span 模板直接读取 index/status，无需 h 或额外渲染函数。

### 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)

Use `status: 'error'` to mark a step as 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)

Custom icons via `items.icon` (data API with programmatic VNodes).

### 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)

Inline steps (content shows in a 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` collapses hidden ranges into ellipsis steps.

### 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)

Navigation-style steps.

### 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)

Panel-style steps with arrow separators.

### 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` shows a progress ring on the current step.

### 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)

Debug: progress ring at 100 percent.

### 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)

Dot-style steps (`type="dot"`; custom dot rendering via the `#progressDot` scoped slot).

### 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)

The most basic usage.

### 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)

Small-size steps.

### 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)

Cooperate with buttons to switch to the next step.

### 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)

Steps within steps (approximated by composition in v1; see 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)

Semantic `classNames` and `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)

Place the title under the icon (`titlePlacement="vertical"`).

### 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)

Debug: `filled` / `outlined` variants.

### 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)

A vertical step bar.

### 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 scoped slots (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


A switch selector.

## When To Use

- To represent an **on / off** state that takes effect immediately (no confirm step).
- Compared with Checkbox: a switch means "a state applied right away"; a checkbox means
  "a choice to be submitted".

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/switch/demo) (7 demos, covering the main antd scenarios.

## API

| Property | Description | Type | Default |
|---|---|---|---|
| checked | Whether the switch is on (controlled) | `boolean` | — |
| defaultChecked | Initial on/off state (uncontrolled) | `boolean` | `false` |
| value | ⚠️ **Alias** for `checked` (antd `@since 5.12.0`) | `boolean` | — |
| defaultValue | ⚠️ **Alias** for `defaultChecked` | `boolean` | — |
| onChange | Listener for the `change` event (**two arguments**; not fired when `disabled`) | `(checked: boolean, event: MouseEvent \| KeyboardEvent) => void` | — |
| onClick | Native click event listener; read state from change / v-model | `(event: MouseEvent) => void` | — |
| checkedChildren | Content shown when on | `VNodeChild` | — |
| unCheckedChildren | Content shown when off | `VNodeChild` | — |
| disabled | Disabled state | `boolean` | — |
| loading | Loading state; ⚠️ **forces** disabled (`\|\|` semantics) | `boolean` | `false` |
| size | Size; ⚠️ `'default'` is deprecated (use `'medium'`) | `'small' \| 'medium' \| 'middle' \| 'default'` | — |
| autoFocus | Focus automatically | `boolean` | — |
| title / id / tabIndex | Native attributes (rendered on `<button>`) | — | — |
| class / style | **Native root attrs** (not Props) | — | — |
| classNames / styles | Semantic slots `{ root, content, indicator }` (object or function) | — | — |

`checked` takes precedence over `value`, and `defaultChecked` over `defaultValue`. Defaults apply only during initialization. Controlled interactions propose an update and wait for the parent to accept it; removing both controlled values retains the last accepted state.

### Slots

| Slot | Description |
|---|---|
| checkedChildren | On-state content; takes precedence over its prop whenever present, including intentionally empty content |
| unCheckedChildren | Off-state content; takes precedence over its prop whenever present, including intentionally empty content |

Slots read current content on each render and fall back to the matching prop when withdrawn. Text, numbers including `0`, VNodes and arrays are supported.

### ConfigProvider

`components.switch` accepts `SwitchConfig`: `className`, `style`, `classNames` and `styles`. Classes concatenate within each region. Styles merge in this order: Provider `styles`, Provider root `style`, component `styles`, native root `style`; later values win. Replacing or removing the configuration updates the existing button.

An omitted `disabled` or `size` follows `componentDisabled` or `componentSize`. The global `large` size resolves to Switch's regular `medium` size. Explicit component props take precedence, while `loading` always disables interaction. Semantic functions receive the current resolved `size` and `disabled`.

### Events

| Event | Description | Payload |
|---|---|---|
| update:checked | `v-model:checked` channel (emitted together with `onChange`) | `boolean` |
| update:value | `v-model:value` channel (the alias channel, same as above) | `boolean` |
| change | Declared Vue event; emitted once per click or arrow-key update, suppressed when disabled | `(checked: boolean, event: MouseEvent \| KeyboardEvent)` |
| click | Native button click, including keyboard activation; arrows do not synthesize click | `MouseEvent` |

`@change` and `onChange` register the same event. They do not attach an additional native DOM `change` listener. `@click` receives only the native `MouseEvent`, supporting `.stop`, `.prevent` and `.once`. The old `(checked, event)` callback is removed directly, without a compatibility layer or deprecation period. Read state from `@change` or `v-model:checked`.

Native root `style` accepts strings, objects and arrays, merged with semantic root styles using Vue rules; caller styles take precedence.
Native lowercase `tabindex` / `autofocus` also reach the button; explicit `tabIndex` / `autoFocus` props take precedence when both are supplied.

### Keyboard

| Key | Behaviour |
|---|---|
| `ArrowLeft` | Turn off (no effect when `disabled`) |
| `ArrowRight` | Turn on (no effect when `disabled`) |
| `Space` / `Enter` | Native `<button>` activation (same as click) |

Arrow keys use standard `KeyboardEvent.key` and prevent scrolling. Space/Enter use native button activation, producing one click and state change.

## Ref

| Name | Type |
|---|---|
| nativeElement | `HTMLButtonElement \| null` |
| focus / blur | `(options?: FocusOptions) => void` / `() => void` |

> ⚠️ antd's `ref` is the `HTMLButtonElement` itself; we expose an object following the
> library convention (`ref.current.focus()` → `ref.value.focus()`).

## Theme (Component Token)

13 tokens, covering the main antd scenarios.

| Token | Description | Default |
|---|---|---|
| trackHeight | Height of Switch | `22px` |
| trackHeightSM | Height of small Switch | `16px` |
| trackMinWidth | Minimum width of Switch | `44px` |
| trackMinWidthSM | Minimum width of small Switch | `28px` |
| trackPadding | Padding of Switch | `2px` |
| handleBg | Background colour of the handle | `#fff` |
| handleShadow | Shadow of the handle | `0 2px 4px 0 rgba(0,35,11,0.2)` |
| handleSize | Size of the handle | `18px` |
| handleSizeSM | Size of the small handle | `12px` |
| innerMinMargin | Minimum margin of the content area | `9px` |
| innerMaxMargin | Maximum margin of the content area | `24px` |
| innerMinMarginSM | Minimum margin of the small content area | `6px` |
| innerMaxMarginSM | Maximum margin of the small content area | `18px` |

Configure these 13 fields through `ConfigProvider.theme.components.Switch`. Numeric lengths receive `px`; CSS length strings are also supported. Unspecified fields derive from the current global theme. Nested themes override only supplied fields, and replacing or removing configuration updates the existing button. The former D50 limitation of fixed component tokens is resolved; static CSS retains default values.

```vue
<ConfigProvider :theme="{ components: { Switch: { trackHeight: 14, handleSize: 20 } } }">
  <Switch aria-label="Custom switch" />
</ConfigProvider>
```

Theme variables merge before Provider styles, component semantic root styles and native root `style`; those root styles can override individual CSS variables. With a custom `prefixCls`, component variables use the current prefix and require matching static CSS.

## FAQ

**Can disabled switches emit click?**
Browsers suppress real user activation and native button `.click()`, so neither click nor change/update fires. Explicit `dispatchEvent` remains a normal DOM dispatch: listeners receive the native event, while disabled state and change/update remain unchanged.

**What is the difference between `value` and `checked`?**
None — `value` / `defaultValue` are aliases for `checked` / `defaultChecked` (added by
antd 5.12.0 for form usage). When both are given, `checked` wins.


## Basic (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)

`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` 表示正在加载：把手位置显示一个转圈图标，并**强制**不可交互。

### 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)

`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 and icon (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>
```

## Semantic styles (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>
```

## Component 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

A table displays rows of data.

## When To Use

- Use to display a collection of structured data in rows;
- Use when users need to sort, search, paginate or perform custom operations on the data.

## Import

```ts
import { Table } from '@apollo-design/ui';
```

## API

The `drag-reorder` example combines existing onRow/onHeaderCell hooks with native row/header drag events, controlled ordering, and keyboard-accessible move/reset buttons. Table gains no built-in drag API.

### Table

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| bordered | Whether to show all cell borders | boolean | false |
| caption | Accessible caption of the table (`<caption>`) | VNodeChild | - |
| columns | Columns description, see below | ColumnsType | - |
| components | Override default table elements | TableComponents | - |
| dataSource | Data record array | T[] | - |
| direction | Text direction | `'ltr' \| 'rtl'` | - |
| expandable | Expandable configuration | ExpandableConfig | - |
| getPopupContainer | Parent node of dropdowns (filter/select) | (triggerNode) => HTMLElement \| ShadowRoot | - |
| indentSize | Indent width in pixels of tree data | number | 15 |
| loading | Whether the table is loading | boolean \| SpinProps | false |
| locale | Default messages, see below | TableLocale | - |
| pagination | Pagination config; set to false to hide | false \| TablePaginationConfig | - |
| rowClassName | Row className | string \| (record, index) => string | - |
| rowKey | Row key field or function | string \| keyof T \| (record) => key | 'key' |
| rowSelection | Row selection configuration | TableRowSelection | - |
| scroll | Horizontal / vertical scroll config | TableScrollConfig | - |
| showHeader | Whether to show table header | boolean | true |
| size | Size of the table | `'large' \| 'middle' \| 'small'` | 'large' |
| sortDirections | Supported sort orders | SortOrder[] | `['ascend', 'descend']` |
| sticky | Sticky header | boolean \| TableSticky | - |
| tableLayout | Table layout algorithm | `'auto' \| 'fixed'` | 'auto' |
| virtual | Enable virtual scrolling (requires `scroll.x` / `scroll.y`) | boolean | false |
| onRow | Row event passthrough (click, mouseenter, ...) | (record, index) => Record<string, unknown> | - |
| onHeaderRow | Header row event passthrough | (columns, index) => Record<string, unknown> | - |

Numeric `scroll.y` values are CSS pixels; `0` keeps an explicit zero-height body. Non-virtual tables also accept CSS length strings; removing `scroll.y` removes that height limit. Virtual tables require numeric `scroll.x` and `scroll.y`.


### Slots

| Name | Scope | Content |
| --- | --- | --- |
| title / footer / summary / caption | `{ data: T[] }` | Current page title, footer, summary and accessible caption |
| emptyText | `{ data: T[], locale }` | Empty content; a present slot, including an empty result, wins over locale.emptyText |
| expandedRow | `{ record: T, index, indent, expanded }` | Expanded content |
| expandIcon | `{ prefixCls, record: T, expanded, expandable, onExpand }` | Call `onExpand(record, event)` to propose a toggle |
| headerCell | `{ column, title }` | Header content inside the existing sorting/filtering controls |
| bodyCell | `{ text, record: T, index, column, originNode }` | Cell content; originNode is the data renderer result |
| paginationItemRender | `{ page, type, element }` | Pagination item |
| paginationTotal | `{ total, range }` | Pagination total |
| paginationSizeChanger | PaginationSizeChangerInfo | Page size control |

Per-column render/title/filterDropdown/filterIcon/sortIcon and selection renderCell/columnTitle remain data services. shouldCellUpdate controls the data renderer cache; native slots continue tracking their own Vue dependencies. Replacing the renderer or changing the row index invalidates the cache.

### Emits and accepted state

`@change` receives `(pagination, filters, sorter, { currentDataSource: T[], action })`. `@scroll` receives the real Event from the current body, including virtual bodies. Each pagination, sorting, filtering, selection and expansion state has one accepted source. Notifications describe proposals; rejected controlled proposals do not replace accepted UI state or caches. Removing control resumes the latest accepted value.

### Generics and refs

Templates infer User from `User[]` and `ColumnsType<User>` without an index signature. Programmatic calls use `h(Table<User>, props, slots)` and `TableSlots<User>`. A TableRef exposes nativeElement() and scrollTo({ top, key, index, align, offset }); align supports start/center/end/nearest.

A custom components.body service receives `(data, { scrollbarSize, ref, onScroll })`. Bind ref to an actual HTMLElement and forward native scroll events to onScroll. This explicit service takes precedence over the built-in virtual body. Element components forward native attrs and their default slot. A virtual wrapper requires one HTMLElement root; fragment/text roots have no measurable container and expose null. Root replacements rebind observation and native scroll access.

The summary slot accepts the named exports `Summary`, `TableSummaryRow` and `TableSummaryCell`. The latter two are the same components as `Summary.Row` and `Summary.Cell`, also available to template auto-import tools.

### Migration

Full-table title/footer/summary/expandedRowRender/expandIcon/emptyText callbacks, including nested expandable content callbacks, move to the named slots above with named scope fields. locale.emptyText keeps static VNodeChild content; dynamic content uses #emptyText. Replace filterDropdownProps.dropdownRender with the column's filterDropdown data renderer. Row/cell services return Vue native attrs such as onKeydown. Subscribe to owned notifications with @change/@scroll.

getCheckboxProps follows the actual selection kind: checkbox/radio change receives `(event: Event, checked: boolean)`; selection notifications retain that same native event. Native class/style target the outer root. Semantic styles use Vue CSSProperties, including undefined and --custom properties.

### ColumnsType

`onCell(record, rowIndex)` returns native cell attributes, including `colSpan`, `rowSpan` and event listeners. A zero span omits that cell; another spanning cell must cover its position.

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| align | Alignment of the column content | `'left' \| 'right' \| 'center'` | - |
| colSpan | Span of the header column (0 hides the header) | number | - |
| onCell | Cell attributes, spans and native events | (record: T, rowIndex) => Record<string, unknown> | - |
| onHeaderCell | Header cell event passthrough | (column) => Record<string, unknown> | - |
| defaultSortOrder | Default sort order | `'ascend' \| 'descend'` | - |
| ellipsis | Ellipsize long content to a single line | boolean \| { showTitle?: boolean } | false |
| filters | Filter menu items of the header | ColumnFilterItem[] \| boolean | - |
| filterDropdown | Custom filter panel | VNodeChild \| (props) => VNodeChild | - |
| filterIcon | Custom filter icon | VNodeChild \| (filtered) => VNodeChild | - |
| filterMode | Filter menu mode | `'tree' \| 'menu'` | 'menu' |
| filtered | Whether the data is filtered (highlights the icon) | boolean | false |
| filteredValue | Controlled filtered value | FilterValue \| null | - |
| filterMultiple | Whether multiple filters are allowed | boolean | true |
| filterSearch | Whether the filter menu is searchable | boolean \| (input, record) => boolean | false |
| fixed | Fixed column | `'left' \| 'right'` | false |
| responsive | Show the column when any listed breakpoint matches | Breakpoint[] | - |
| rowSpan | Row span | number | - |
| render | Renderer of the cell, **positional args** `(value, record, index)` | (value, record, index) => VNodeChild | - |
| showSorterTooltip | Sorter tooltip of the header | boolean \| SorterTooltipProps | true |
| sortOrder | Controlled sort order | `'ascend' \| 'descend' \| null` | - |
| sorter | Sort function; true delegates ordering to the consumer | boolean \| CompareFn | false |
| title | Title of the column | VNodeChild \| ColumnTitle | - |
| width | Column width (required for fixed columns with scroll.x) | number \| string | - |
| children | Children of a grouped column | ColumnsType | - |
| onFilter | Local filter function | (value, record) => boolean | - |
| onFilterDropdownOpenChange | Callback when the filter panel opens/closes | (open) => void | - |

### TableRowSelection

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| checkStrictly | Whether parent/child nodes are related under checkable mode | boolean | true |
| columnTitle | Custom title of the selection column | VNodeChild | - |
| columnWidth | Custom width of the selection column | number \| string | - |
| fixed | Whether the selection column is fixed | boolean \| `'left' \| 'right'` | - |
| getCheckboxProps | Default props of the checkbox | (record) => Record<string, unknown> | - |
| preserveSelectedRowKeys | Keep keys of removed rows in the selection | boolean | - |
| renderCell | Renderer of the selection cell | (checked, record, index, originNode) => VNodeChild | - |
| selectedRowKeys | Controlled selected row keys | TableKey[] | - |
| selections | Custom selections (`SELECTION_ALL` / `SELECTION_INVERT` / `SELECTION_NONE` ...) | SelectionItem[] \| true | - |
| type | Checkbox or radio | `'checkbox' \| 'radio'` | 'checkbox' |
| onChange | Callback when the selection changes | (selectedRowKeys, selectedRows, info) => void | - |
| onSelect | Callback when a row is selected manually | (record, selected, selectedRows, nativeEvent) => void | - |
| onSelectAll | Callback when select-all / deselect-all | (selected, selectedRows, changeRows) => void | - |
| onSelectInvert | Callback when inverting the selection | (selectedRowKeys) => void | - |
| onSelectNone | Callback when clearing the selection | () => void | - |

### ExpandableConfig

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| childrenColumnName | Field name of tree children | string | 'children' |
| columnTitle | Custom title of the expand column | VNodeChild | - |
| columnWidth | Custom width of the expand column | number \| string | - |
| defaultExpandAllRows | Expand all rows initially | boolean | false |
| defaultExpandedRowKeys | Initially expanded rows | TableKey[] | - |
| expandedRowClassName | className of the expanded row | string \| (record, index, indent) => string | - |
| expandedRowKeys | Controlled expanded rows | TableKey[] | - |
| expandIconColumnIndex | Column index of the expand button | number | - |
| indentSize | Indent width of tree data | number | 15 |
| rowExpandable | Whether the row is expandable | (record) => boolean | - |
| showExpandColumn | Whether to show the expand column | boolean | true |
| onExpand | Callback when a row is expanded | (expanded, record) => void | - |
| onExpandedRowsChange | Callback when expanded rows change | (expandedRows) => void | - |


| fixed | Fixed position of the expand column | `'left' \| 'right' \| 'start' \| 'end'` | - |

Put native pager root attrs in pagination.class / pagination.style; replace the old className entry with class.

### pagination

Extends all `Pagination` props, plus:

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| position | Position of the pagination | `['topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight']` | `['bottomRight']` |
| hideOnSinglePage | Hide the pagination when there is a single page | boolean | false |

> Set `pagination: false` to hide the pagination. Default page size is 10.

Pagination content uses #paginationItemRender="{ page, type, element }", #paginationTotal="{ total, range }" and #paginationSizeChanger="info". Each pager receives its current scope, including top/bottom pagers and dynamic slots. Configuration holds data and business events; itemRender/showTotal/sizeChangerRender function entries are removed.

## Current theme variables

Derived header, sorting, hover and filter-popup colours follow the current ConfigProvider theme. Existing Table component token overrides support replacement, removal and zero sizes. Native root CSS variables take precedence; filter portals use the same theme source. The forty default light CSS declarations are unchanged.


## 基础用法 (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>
```

## Reorder rows and columns (drag-reorder)

Use existing `onRow` and column `onHeaderCell` hooks to bind native browser drag events, then update the controlled `dataSource` or `columns` order. Rows and columns have separate drop targets. Keyboard-accessible buttons provide equivalent moves and reset. This consumer example adds no built-in drag prop or third-party drag runtime to Table.

### 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-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 (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 (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>
```

## Tree Filter Search (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 Header in Container (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` 同时在上方与下方渲染分页器，可切换位置并实时同步当前页码。

### 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>
```

## Component 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 (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>
```

## Editable Row (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>
```

## Ellipsis Custom 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 (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 (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-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 (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` 配置每页条数、快速跳页与总数展示；翻页或在每页条数下拉框中切换后，页面标签会同步当前页码与页大小。

### 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 (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 (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 (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 (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

Tabs make it easy to switch between different views.

## When To Use

- When there is a group of content on the same level.
- When there is a need to switch between views within a region.

## Import

```ts
import { Tabs } from '@apollo-design/ui';
```

## Examples































## API

### Tabs

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| activeKey | Controlled selection; supports `v-model:activeKey` | `string` | — |
| defaultActiveKey | Initial uncontrolled selection | `string` | First enabled item |
| items | Tab and panel data | `TabsItem[]` | `[]` |
| type | Tab appearance | `'line' \| 'card' \| 'editable-card'` | `'line'` |
| size | Local size, then components.tabs.size, then global size | `'small' \| 'medium' \| 'middle' \| 'large'` | — |
| tabPlacement | Navigation position; start/end follow text direction | `'top' \| 'end' \| 'bottom' \| 'start'` | `'top'` |
| direction | Text direction; otherwise reads the current Provider | `'ltr' \| 'rtl'` | — |
| centered | Center navigation | `boolean` | `false` |
| tabBarGutter | Space between tabs in px | `number` | — |
| tabBarStyle | Navigation styles | `CSSProperties` | — |
| tabBarExtraContent | Additional content; a single node appears on the right | `VNodeChild \| { left?: VNodeChild; right?: VNodeChild }` | — |
| addIcon / removeIcon | Add and close button icons | `VNodeChild` | — |
| hideAdd | Hide the editable-card add button | `boolean` | `false` |
| more | Overflow button icon and popup motion name | `{ icon?: VNodeChild; transitionName?: string }` | — |
| indicator | Alignment and size; the function receives the original length | `{ align?: 'start' \| 'center' \| 'end'; size?: number \| ((origin: number) => number) }` | `{ align: 'center' }` |
| animated | Indicator and panel motion | `boolean \| { inkBar?: boolean; tabPane?: boolean }` | `{ inkBar: true, tabPane: false }` |
| destroyOnHidden | Panel destruction default when the item does not specify one | `boolean` | `false` |
| locale | Accessible names for buttons and the overflow list | `{ dropdownAriaLabel?: string; removeAriaLabel?: string; addAriaLabel?: string }` | English names |
| getPopupContainer | Overflow popup container | `(trigger: HTMLElement) => HTMLElement` | Current Provider / body |
| classNames / styles | Semantic objects, or `({ props: TabsProps }) => object` | `TabsProps['classNames'] / TabsProps['styles']` | — |
| id | Root id and internal ARIA id prefix | `string` | Vue useId() |
| prefixCls | DOM class prefix | `string` | `'apollo-tabs'` |

Existing deprecated aliases remain: tabPosition (top/right/bottom/left), indicatorSize, moreIcon, popupClassName and destroyInactiveTabPane. Prefer tabPlacement, indicator.size, more.icon, classNames.popup.root and destroyOnHidden.

### TabsItem

| Field | Description | Type |
| --- | --- | --- |
| key | Unique data key; events return its original value | `string` |
| label / children | Tab label / panel content; full Vue content including numeric zero | `VNodeChild` |
| icon | Label icon | `VNodeChild` |
| disabled | Block user activation and removal | `boolean` |
| closable | Allow removal in editable-card | `boolean` |
| closeIcon | With closable omitted, null/false disables removal for this item | `VNodeChild` |
| forceRender | Render before the first activation | `boolean` |
| destroyOnHidden | Override the component default, including explicit false | `boolean` |
| destroyInactiveTabPane | Deprecated destroyOnHidden alias | `boolean` |
| className / style | Panel class and style | `string / CSSProperties` |

### Events

| Event | Trigger and arguments |
| --- | --- |
| update:activeKey | A selection request differs from the current public value: `(key: string)` |
| change | Sent with update:activeKey: `(key: string)` |
| tabClick | Every valid click or keyboard activation, including the current tab: `(key: string, event: MouseEvent \| KeyboardEvent)` |
| tabScroll | Navigation movement: `({ direction: 'left' \| 'right' \| 'top' \| 'bottom' })` |
| edit | Add: `(event, 'add')`; remove: `(key, 'remove')`. The caller updates items. |

Vue emits owns event delivery. Controlled requests change the public value only after the parent accepts them. Removing control with undefined retains the last accepted value. Defaults initialize once. Removing the uncontrolled active item chooses a nearby enabled item using its former index; data normalization does not emit user activation events.

### Slots and instance

| Slot | Scope |
| --- | --- |
| tabBar | TabsRenderTabBarProps: current id, prefixCls, tabs, activeKey, direction, placement, motion, semantic styles and navigation callbacks; replaces navigation |
| popupRender | `{ originNode, restTabs, onClose }`: default overflow list, current hidden items and close action |
| extra | `{ position: 'left' \| 'right' }`: additional content |

Slots are read during rendering. An extra slot takes priority over tabBarExtraContent, including an intentionally empty slot. popupRender also supports conditional addition, empty content and removal. A custom tabBar owns its keyboard and ARIA behavior. editable.onEdit requires `{ key, event }` for remove and `{ event }` for add.

A template ref exposes the actual root as the readonly `nativeElement: HTMLElement | null` property: `tabsRef.value?.nativeElement`. Do not call nativeElement().

### Native attrs, ownership and focus

class, style, data-*, ARIA and undeclared native events land on the root div. Native style accepts objects, arrays and strings and overrides semantic root styles. Semantic regions are root, header, item, remove, indicator, body, content and nested popup.root. Provider styles merge first, followed by local semantic styles and native root style. Semantic functions receive current resolved props.

Tabs and close buttons have separate interaction ownership. tablist uses aria-owns to own only tabs; the overflow listbox owns only options, with independent remove buttons. Data-key segments in ids are encoded to preserve ARIA references. Vue generates deterministic SSR/hydration ids when id is omitted. Reordering an existing key retains its panel input and component state.

| Key | Behavior |
| --- | --- |
| Left / Right | Cycle through enabled horizontal tabs; reverse for RTL; prevent handled page scrolling |
| Up / Down | Navigate vertical tabs; preserve normal page behavior for horizontal tabs |
| Home / End | First / last enabled tab |
| Enter / Space | Activate the focused tab |
| Backspace / Delete | Request removal when allowed; move focus only after the item is actually removed |
| Up / Down / Enter / Space on overflow | Open and focus the list; Up starts from the last option |
| Up / Down, Home / End in overflow | Move among enabled options |
| Enter / Space, Escape in overflow | Select and close / close; restore focus to the overflow button |

Overflow supports hover and click, with outside clicks closing it. Remove buttons and custom slot form controls retain their own keyboard activation. A disabled controlled selection keeps an enabled Tab entry available. Touch motion, inertia, observers and popup listeners are released on cancellation, target replacement and unmount.

## Design Token

The 24 consumed component tokens read current ConfigProvider.theme.components.Tabs, including nesting, replacement, removal and global derivation. Numeric lengths use px; zIndexPopup is unitless. The popup uses the same current tokens.

| Token | Default / derivation |
| --- | --- |
| zIndexPopup | 1050 |
| cardBg / cardGutter | colorFillAlter / 2 |
| cardHeight / cardHeightSM / cardHeightLG | 40 / 32 / 48; add-button minimum size and default padding derivation |
| cardPadding / cardPaddingSM / cardPaddingLG | 8px 16px / 4px 8px / 11px 16px; recalculated after height overrides; explicit padding wins |
| titleFontSize / titleFontSizeLG / titleFontSizeSM | 14 / 16 / 14 |
| inkBarColor | colorPrimary |
| horizontalMargin | 0 0 16px 0 |
| horizontalItemGutter | 32; configurable |
| horizontalItemPadding / horizontalItemPaddingSM / horizontalItemPaddingLG | 12px 0 / 8px 0 / 16px 0 |
| verticalItemPadding / verticalItemMargin | 8px 24px / 16px 0 0 0 |
| itemColor | colorText |
| itemSelectedColor / itemHoverColor / itemActiveColor | colorPrimaryTextActive on light backgrounds; colorPrimaryTextHover on dark backgrounds |

The default text states reuse existing readable theme colors. Background classification follows Button and generates no new color values. Explicit item*Color, native styles, transparent or custom backgrounds require the caller to ensure the actual contrast pair. Static CSS consumes the variables; custom prefixCls requires matching static selectors.

### Development migration

Remove inert top-level children and use items[].children. Removed horizontalItemMargin / horizontalItemMarginRTL never affected CSS; use horizontalItemGutter. The previously declared nativeElement property now returns the actual root; replace old runtime function calls with property reads. IDs now exist during SSR and encode data-key segments. item.destroyOnHidden now overrides the component default as already documented. These corrections have no compatibility layer or deprecation period.

The existing single-object popupRender and conditional slot delivery remains valid; see the [2026-10-24 migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/tabs-popup-slots.md). Original DOM and visual references remain intact. Focused stage-one checks are separate from frozen-version final library acceptance.


## Basic (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 (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>
```

## With Icon (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)

`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 (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 (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` 让卡片式页签整体居中。

### 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 (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 (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 content (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 (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 (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)

`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 Tabs (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>
```

## Component 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 (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 (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 (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>
```

## Custom overflow popup (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 (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


Label attributes and categories. Use CheckableTag or CheckableTagGroup for selection.

## Examples

All twelve [demos](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/tag/demo) are retained: basic links/closing, selection, colours, dynamic input, customization, disabled state, dragging, icons, status, semantic styles, close/reset and component tokens.

## API

### Tag

| Prop | Description | Type | Default |
|---|---|---|---|
| prefixCls | DOM class prefix; custom prefixes require matching static CSS | `string` | `apollo-tag` |
| color | Thirteen presets, success/processing/error/warning/default, or a valid CSS colour | `TagColor` | — |
| variant | Appearance | `'filled' \| 'solid' \| 'outlined'` | `filled` |
| bordered | Existing deprecated field; false selects filled. Use variant | `boolean` | — |
| closable | Close switch/configuration: closeIcon, disabled, aria-* and data-* | `boolean \| TagClosableConfig \| null` | `false` |
| href / target | Inner link URL / target | `string` | — |
| disabled | Disable link and close; omission uses the global disabled setting | `boolean` | `false` |
| classNames / styles | Four regions: root, icon, content and close | `TagSemanticClassNames / TagSemanticStyles` | — |

| Slot | Content |
|---|---|
| default | Complete label content |
| icon | Complete leading content |
| closeIcon | Complete close content; a present slot wins over configuration, including intentionally empty content |

`close` emits the native MouseEvent. `preventDefault()` cancels hiding; close clicks stop propagation outside the label. The root is a stable span with owned semantic hosts. href creates an anchor inside content; the native close button is its sibling. Caller glyph attributes and handlers remain intact. Close owns Enter/Space keydown propagation while preserving native activation, so ancestor selection widgets do not process the same key. Closing retains DOM with the `-hidden` class; a parent may unmount/remount to reset visibility.

### CheckableTag

| Prop | Description | Type | Default |
|---|---|---|---|
| prefixCls | Tag prefix | `string` | `apollo-tag` |
| checked | Controlled state, supports `v-model:checked`; omission is uncontrolled | `boolean` | `false` |
| disabled | Disable selection | `boolean` | `false` |

Slots: default and icon, with complete content. Events: `update:checked(boolean)`, `change(boolean)`, `click(MouseEvent)` and `keydown(KeyboardEvent)`. Click/Space updates once. Enter does not toggle; repeated Space does not repeat updates. Native `preventDefault()` cancels toggling. The component owns checkbox role, aria-checked and disabled tabindex.

### CheckableTagGroup

| Prop | Description | Type | Default |
|---|---|---|---|
| id / prefixCls | Root id / tag prefix; group appends -checkable-group | `string` | — / `apollo-tag` |
| options | Values or option objects; omitted label displays value | `(T \| CheckableTagOption<T>)[]`, T is string/number | `[]` |
| value | Controlled model, supports `v-model:value` | Single `T \| null`; multiple `T[]` | — |
| defaultValue | Initial uncontrolled value, read at mount | Same as value | Single null; multiple [] |
| multiple | Multiple selection | `boolean` | `false` |
| disabled | Disable all options | `boolean` | `false` |
| classNames / styles | root/item only; option style wins over styles.item | `GroupSemanticClassNames / GroupSemanticStyles` | — |

Options contain value, optional label (VNodeChild data), className and style. Group has no public slots. Events: `update:value(value)` and `change(value)`, typed by multiple and emitted once per interaction. Current options/multiple/value update rendering; mode changes do not rewrite the parent model, and the next interaction emits the current mode's shape. Selecting an already selected single item clears it to null. Zero and empty strings are valid values.

## Expose, attrs and Provider

All three expose `nativeElement`: the root span for Tag/CheckableTag and div for Group. Tag.CheckableTag and Tag.CheckableTagGroup retain identity with the named exports. Root class/style/id/data/listeners follow Vue merging, including string/array/object styles; native root style wins over semantic styles. Use Vue `@keydown` for keyboard events.

For linked tags, rel/download/hreflang/referrerpolicy/tabindex/accesskey, aria-label/labelledby/describedby and focus/blur listeners land on the actual anchor; other attrs land on the root. Current Provider direction, disabled and components.tag styles remain reactive. Tag also consumes variant/closable/closeIcon/classNames/styles; selection components do not consume Tag closing/variant configuration. Explicit local fields override Provider values and removal restores current configuration.

## Theme

| Component token | Default source | Purpose |
|---|---|---|
| defaultBg | colorFillTertiary composited over colorBgContainer | Default surface |
| defaultColor | colorText | Default text |
| solidTextColor | Black/white chosen from the actual solid surface | Solid text; explicit configuration retains caller control |

Configure through ConfigProvider.theme.components.Tag; replacement/removal is reactive. Filled/outlined preset/status/custom text adapts lightness to the current theme. Solid and selection states choose text against their actual surface. Pair explicit foreground overrides with a suitable background. See the [development migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/tag-contracts.md) for changes and validation status.


## Basic (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 (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 (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>
```

## Add & Close Dynamically (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 (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)

禁用状态的标签（关闭按钮与交互均禁用）。

### 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 (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)

通过 `#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 (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>
```

## Semantic classNames and styles (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>
```

## Close and reset (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>
```

## Component 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


Choose a single time or use `TimeRangePicker` for a time range.

> Current contract, 2026-10-30: both entries have a fixed time axis. The actual models are `value`, `open` and `pickerValue`. Unsupported `mode/defaultMode/update:mode` declarations are removed. Content uses named slots, notifications use emits, and DOM handles are nullable.

## Examples

See the 16 implemented [demos](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/time-picker/demo).

## API

| Property | Meaning | Default |
|---|---|---|
| value / defaultValue | Dayjs value; a single value may be null, a range has two endpoints | — |
| open / defaultOpen | Current open state / initial uncontrolled state | — |
| pickerValue / defaultPickerValue | Browsing time / initial browsing time | — |
| defaultOpenValue | Empty panel template, without committing a value | — |
| format | Display/parser format, formatter or mask | `HH:mm:ss` |
| use12Hours | Show meridiem | `false` |
| showHour / showMinute / showSecond / showMillisecond | Visible columns, inferred from format when omitted | — |
| hourStep / minuteStep / secondStep / millisecondStep | Unit steps | `1` |
| disabledTime | Disabled units; range callbacks also receive range and `{ from }` | — |
| hideDisabledOptions | Hide disabled units | `false` |
| needConfirm | Require confirmation; false commits when leaving the panel | `true` |
| changeOnScroll | Select the nearest enabled unit after scrolling stops for 300ms | `false` |
| inputReadOnly | Prevent typing while retaining panel selection | `false` |
| allowClear | Clear button; accepts `{ clearIcon }` | `true` |
| disabled / size / status / variant | Disabled state, size, validation and variant | variant: `outlined` |
| classNames / styles | Current semantic classes/styles, including function forms | — |
| prefix / suffixIcon / clearIcon | Static decoration, also available as named slots | Clock suffix |
| placeholder / locale | Input hint and language | `Select time` |
| presets | Preset values, including values evaluated at interaction time | — |

TimeRangePicker additionally supports separator, allowEmpty and per-endpoint disabled states. Calendar navigation, multiple tags and calendar mode switching are not part of the time-axis API.

Native input metadata goes to the actual input; class/style/data attributes go to the root. A range id string identifies the start input; `{ start, end }` identifies both endpoints. Exposed methods are focus and blur, with nullable nativeElement; range refs also expose nullable startInput/endInput.

## Events and slots

Semantic change/openChange/pickerValueChange events accompany their update:value/update:open/update:pickerValue proposals. Rejected controlled proposals never become hidden accepted values; releasing control retains the last accepted value. Other events are calendarChange, ok, clear, focus, blur, invalid and panelChange; the single picker also emits select. Keydown receives one native KeyboardEvent and honors preventDefault().

Single-picker slots are prefix, suffixIcon, clearIcon, panelRender, extraFooter, cellRender and presetRender. Range adds separator. CellRender receives `{ current, info }`, panelRender receives `{ originPanel }`, and extraFooter receives `{ mode }`. Explicitly empty slots remain empty and current slot presence is reactive. Legacy render props and addon are removed.

For readonly inputs, ArrowDown enters the panel, arrows navigate enabled units, Enter/Space selects and Escape restores input focus. Use the OK button to confirm under the default confirmation policy.

## Configuration and styles

Both entries read the current components.timePicker configuration, including root classes/styles, semantic configuration, variant, icons and range separator. Input hints follow the current locale.TimePicker fragment, with explicit local placeholder/locale values taking precedence. DatePicker and rangePicker configurations do not leak into Time entries. Ordinary DateRangePicker retains its rangePicker owner.

TimePicker reuses DatePicker static CSS and theme variables. It has no independent Component Token, stylesheet or PurePanel. Existing deprecated popupClassName/popupStyle/bordered/dropdownClassName inputs remain; prefer semantic styles and variant.

TimePickerWithRange.RangePicker and the named TimeRangePicker refer to the same component.


## Basic (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 (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 (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 (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)

禁用状态。

### 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 (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 (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 (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 (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)

`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>
```

## Semantic style (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>
```

## Prefix and Suffix (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>
```

## Under Control (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>
```

## Variants (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 Hours (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 (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


Display ordered events, their status and rich descriptions in a vertical or horizontal timeline. The root is a native `<ol>` and each item is an `<li>`. Timeline composes the internal Steps renderer; it has no selection state or business events.

## Examples

The fifteen paired examples in `demo/` cover basic content, variants, end placement, title columns, horizontal and alternating layouts, loading, legacy pending data, custom icons, long text, titles, semantic styles, native slots and live component tokens.

## API

### Timeline

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| items | Ordered item data; use native item slots for template content | `TimelineItemType[]` | — |
| mode | Item placement; legacy left/right normalize to start/end | `'start' \| 'end' \| 'alternate' \| 'left' \| 'right'` | `'start'` |
| orientation | Explicit direction at every viewport width | `'horizontal' \| 'vertical'` | `'vertical'` |
| titleSpan | Title column: numbers use 24-grid units; strings use CSS lengths/percentages | `number \| string` | — |
| variant | Node variant | `'filled' \| 'outlined'` | `'outlined'` |
| reverse | Reverse display order; rail status follows the current item | `boolean` | `false` |
| pending | Deprecated: append a loading item in items instead. false/null/undefined disable it; 0 and an empty string still create a pending item; true shows only its indicator | `VNodeChild` | — |
| pendingDot | Deprecated: custom icon for the synthetic pending item; use items[].icon instead | `VNodeChild` | — |
| classNames | Semantic class names, or a function of current `{ props }` | `TimelineSemanticValue<TimelineSemanticClassNames>` | — |
| styles | Semantic styles, or a function of current `{ props }` | `TimelineSemanticValue<TimelineSemanticStyles>` | — |
| prefixCls | DOM class prefix; arbitrary prefixes require matching static CSS | `string` | `apollo-timeline` |

Vertical timelines use the two-column layout when any current title is nonempty. Explicit mode="alternate" also enables this layout and assigns sides by source-item parity. Reversing changes display order and slot indices while preserving each source item's side. titleSpan is ignored in explicit alternate mode.

Horizontal alternating timelines wrap long titles and descriptions within each column. Shared intrinsic rows keep one aligned axis and grow with content; the semantic wrapper, section and header remain real styling boxes. Content-only vertical timelines use itemPaddingBottom (20px by default, 10px with the compact algorithm).

### Item data

| Field | Description | Type |
| --- | --- | --- |
| key | Stable item identity across replacement/reordering | `string \| number` |
| title / content / icon | Complete Vue content, including 0, fragments and components; explicit false/empty icon suppresses the loading fallback | `VNodeChild` |
| color | blue/red/green/gray use preset classes; other colors use the item's dot-color CSS variable | `string` |
| loading | Process status; absent/null icon and dot use the loading indicator | `boolean` |
| placement | Side; omitted values follow mode | `'start' \| 'end'` |
| className / style | Item root class and inline styles | `string` / `CSSProperties` |
| classNames / styles | Item targets: root, wrapper, header, title, section, content, icon and rail | Semantic objects |
| label / children / dot | Deprecated data aliases for title/content/icon, used only when the matching current field is nullish | `VNodeChild` |
| position | Deprecated placement alias; left/right normalize to start/end; explicit placement wins | `'left' \| 'right' \| 'start' \| 'end'` |

Item root styles merge in this order: component styles.item → item styles.root → item.style. Other regions merge the component target first, then the corresponding item target. There is no subtitle region. Native slots share these same hosts and styling targets.

### Content slots

| Name | Scope | Description |
| --- | --- | --- |
| itemTitle | `{ item, index }: TimelineItemSlotProps` | Item title |
| itemContent | `{ item, index }: TimelineItemSlotProps` | Item body |
| itemIcon | `{ item, index }: TimelineItemSlotProps` | Item icon |

item is the current original source item. index is its display index after reverse, including any legacy pending position. A present slot overrides its matching data and aliases, including when intentionally empty; removal restores the data. Slots render during SSR and hydration. The synthetic pending item has no source-item scope. The default slot does not register items; Timeline.Item and TimelineItemComponent were removed in the development version. See the [slot migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/timeline-item-slots.md).

### Native attrs, events and ref

Native class/style, id, tabindex, ARIA attributes and DOM listeners target the ordered-list root. Native root styles override matching semantic root styles. class supports Vue strings/arrays/objects; style supports strings/arrays/objects. Native @change receives the bubbling DOM Event; it does not enable selectable items. @click and event modifiers use normal Vue DOM semantics. Timeline has no emits or v-model.

A ref exposes `{ nativeElement: HTMLElement | null }`, the current `<ol>` after mounting. The element remains stable through data, layout and Provider updates; unmounting clears the parent ref. Give items explicit keys to retain their input nodes and values when replacing/reordering data.

## Theme

ConfigProvider components.timeline supplies current className/style/classNames/styles defaults. Current direction, theme algorithms and nested component-token overrides are reactive and isolated between instances. Root style priority is current theme → Provider/component semantic root styles → native style.

| Component Token | Description | Default |
| --- | --- | --- |
| tailColor | Rail color | colorSplit |
| tailWidth | Rail width | lineWidthBold |
| dotBorderWidth | Node border width | lineWidthBold |
| itemPaddingBottom | Item bottom spacing | padding * 1.25 |
| dotSize | Custom node size | undefined; keep the internal Steps size fallback |
| dotBg | Custom node background | undefined; keep the internal Steps background fallback |

Set tokens with `:theme="{ components: { Timeline: { dotSize: 14, tailWidth: 3 } } }"` on ConfigProvider, or with root CSS variables such as `--apollo-timeline-dot-size: 14px`. Sizes accept finite nonnegative numbers (converted to px); the width/size tokens also accept CSS length strings. Clearing an optional dot token restores its fallback. Theme updates do not generate runtime stylesheets.

The native event, item-side, zero-content, ref and token corrections are described in the [current contract migration](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/docs/migrations/timeline-contracts.md).


## Basic (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)

`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>
```

## Right alternate (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 (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 (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 (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>
```

## Reverse and pending (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>
```

## Pending (legacy) (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 node (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 (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)

带 `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 and class (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 (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 item slots (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>
```

## Component 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


简单的文字提示气泡框。

## When To Use

- A simple text popup on hover/focus, for lightweight hints.

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | Content data (`0` is valid); use `#title` for template content | `VNodeChild` | — |
| — | ~~`overlay`~~ **已移除**（C8-R2）：富内容走 `#title` 插槽 | — | — |
| 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 | Content id referenced by the trigger's aria-describedby | `string` | Generated |
| fresh / forceRender / disabled | Update hidden content / force mounting / disable | `boolean` | `false` |
| classNames / styles | 语义槽 `root / container / arrow`（含函数式） | — | — |
| overlayStyle / overlayInnerStyle / overlayClassName | ⚠️ 已废弃 | — | — |

### Events

| Name | Payload | Description |
|---|---|---|
| update:open | `boolean` | State proposal for v-model:open |
| openChange | `boolean` | Sent with update:open; a controlled parent accepts the value |
| afterOpenChange | `boolean` | The current open/close motion completed |
| popupClick | `MouseEvent` | Original click event from the tooltip content |

These are Vue emits and support modifiers such as `@open-change.once`. In `h()`, use `onOpenChange`, `onAfterOpenChange` and `onPopupClick`. Empty content follows the suppression rules below.

### 插槽

| 名称 | 说明 |
|---|---|
| default | 触发元素（组件也可；事件与 ref 需透传到根元素） |
| title | Content; takes precedence over the title prop, including an empty slot |

`TooltipSlots` is exported. `TooltipPurePanel` accepts the same title data and named slot. Conditional slots are read during each render.

### Native class/style

`Tooltip` applies native class/style to the popup root; `TooltipPurePanel` applies them to the panel root. Styles accept strings, objects and mixed arrays and override Provider and semantic root styles. Removing them restores the current source. Use `styles.container` for the content container; root styles are never copied there. Other native Tooltip attrs and listeners apply to the trigger. Set the trigger's own class/style directly on the default slot element.

A numeric final root `zIndex`, including `0` and numeric strings, also supplies the descendant layer and overrides the dedicated `zIndex` prop. Provider styles, `styles.root`, `overlayStyle` and native style retain their existing merge order. Conditional `undefined` or empty-string layers and native `false/null/undefined` release the override and restore the remaining source or automatic layer. `calc(...)` / `var(...)` remain valid CSS expressions; deriving descendant numeric layers from them remains deferred.

### Current theme

`ConfigProvider.theme.components.Tooltip` supports numeric `maxWidth` (default 250px) and `zIndexPopup` (default `zIndexPopupBase + 70`). Theme replacement, removal and nesting update the existing popup. Arrow shape, offsets and placement read the same current Alias Token source. Semantic styles and native CSS variables take priority. PurePanel uses the current colors and arrow values while retaining its natural panel width.

### Expose

`forceAlign()`, `nativeElement: HTMLElement | null` and `popupElement: HTMLDivElement | null` (`TooltipRef`). The latter two are current element properties; popupElement becomes null after the closed popup is destroyed.

### Development migration

Replace `:after-open-change="handler"` with `@after-open-change="handler"`, and the object key `afterOpenChange` with `onAfterOpenChange`. Native class/style now apply only to the popup root; set trigger styles on the default slot element. This development correction has no compatibility branch or deprecation period.

## 设计说明

- **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）。
- **Empty content**: an uncontrolled tooltip stays closed and sends no open-change notification. Controlled `open` remains authoritative. `0` is valid; an empty title slot never falls back to the prop.
- 与 antd 的已知差异见组件 README。


## Arrow Point At Center (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)

Support show, hide or keep arrow in the center.

### 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.

### 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)

The simplest usage.

### 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)

We preset a series of colorful Tooltip styles for use in different situations.

### 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)

Please check the debug style of the popup with the developer mode.

### 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 the popup when closed.

### 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)

Prompt something while editing.

### 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)

The tooltip can still be shown when the trigger element is disabled.

### 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)

There are 12 placement options available.

### 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)

Static panels need no trigger. Toggle, update or empty the native title slot. Empty slots override the prop; removing the slot restores the title data. Native string styles merge with semantic root styles.

### 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 into viewport when overflowing the scroll container. The demo scrolls within its own viewport without moving the surrounding document.

### 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)

Smooth transition animation.

### 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)

Semantic `classNames` / `styles` (object and function forms), plus the current Tooltip maxWidth token. Click the third button while the hint is open to change it.

### 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)

Wrap a custom component (events and ref must pass through to the root element).

### 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

A step-by-step guide that highlights page elements with a mask cutout. Supports keyboard navigation and customizable panels.

## When To Use

- To introduce new or redesigned features to users step by step;
- To guide users through a task flow in a specified order;
- To spotlight page elements.

## Import

```ts
import { Tour } from '@apollo-design/ui';
```

## Examples



















## API

### TourProps

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| steps | Tour step configs | TourStepProps[] | - |
| open | Whether the tour is open (`v-model:open`) | boolean | - |
| defaultOpen | Initial open state when uncontrolled (defaults to open when neither `open` nor `defaultOpen` is given and the step is valid) | boolean | - |
| current | Current step (`v-model:current`) | number | 0 |
| defaultCurrent | Initial step when uncontrolled | number | 0 |
| type | Panel type | 'default' \| 'primary' | 'default' |
| arrow | Whether to show the arrow (overridden by `steps[].arrow`) | boolean \| { pointAtCenter } | true |
| placement | Default placement (overridden by `steps[].placement`; falls back to `center` without a target) | TourPlacement | 'bottom' |
| mask | Mask (overridden by `steps[].mask`) | boolean \| { style?, color? } | true |
| gap | Highlight area expansion | { offset?: number \| [number, number]; radius?: number } | offset 6 / radius 2 |
| animated | Highlight animation | boolean \| { placeholder } | true |
| keyboard | Keyboard navigation (Esc / ← / →) | boolean | true |
| closeIcon | Global close icon (`#closeIcon` slot wins; overridden by `steps[].closeIcon`) | VNodeChild | - |
| closable | Whether to show the close button (overridden by `steps[].closable`; `aria-*` on the object pass through) | boolean \| { closeIcon?, ...aria } | - |
| scrollIntoViewOptions | Scroll options when the target is off-screen | boolean \| ScrollIntoViewOptions | { block: 'center', inline: 'center' } |
| zIndex | Popup z-index (computed via `useZIndex` when omitted) | number | - |
| getPopupContainer | Mount container service, with the actual placeholder | (node: HTMLElement) => HTMLElement \| ShadowRoot \| null | - |
| disabledInteraction | Whether the mask blocks all interactions (including inside the hole) | boolean | false |
| builtinPlacements | Custom placement config map | Record&lt;string, AlignType&gt; | - |
| class | **Native root attrs** (replacing upstream `rootClassName`) | string / array / object | - |
| style / id / aria-* / native events | Land once on the actual popup; style supports Vue objects, arrays and strings | Native attrs | - |
| classNames / styles | 12 semantic slots (object or function) | TourSemanticClassNames / TourSemanticStyles | - |

### TourStepProps

See `index.zh-CN.md` for the full table (target / title / description / cover / placement / mask / arrow / style / className / scrollIntoViewOptions / closeIcon / closable / nextButtonProps / prevButtonProps / type / classNames / styles).

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:open | v-model:open | (open: boolean) |
| update:current | v-model:current | (current: number) |
| change | Step changed (emitted together with `update:current`) | (current: number) |
| close | Closed (Esc / close button / Finish), carries the current step | (current: number) |
| finish | Finish clicked on the last step | - |
| popupAlign | Actual popup alignment notification | (element: HTMLElement, align: TriggerAlign) |

### Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| title / description / cover | Step content (wins over the same-name string prop) | { step, current, total } |
| closeIcon | Close icon (wins over the prop) | - |
| nextButton / prevButton | Button text (wins over `*.children`) | { step, current, total } |
| indicators | Custom indicators (mapped to `indicatorsRender`) | { current, total } |
| actions | Custom actions (mapped to `actionsRender`; `originNode` is a stable default-actions component) | { current, total, originNode } |

### TourPurePanel

The counterpart of `Tour._InternalPanelDoNotUseOrYouWillBeFired`. Render fields plus `prefixCls`, `current` (0) and `total` (6); positioning fields are not part of this static preview.

### Theme tokens

| Token | Description | Default |
| --- | --- | --- |
| zIndexPopup | Popup z-index | zIndexPopupBase + 70 (1070) |
| closeBtnSize | Close button size | fontSize × lineHeight = 22px |
| primaryPrevBtnBg | Primary prev-button background | rgba(255,255,255,0.15) |
| primaryNextBtnHoverBg | Primary next-button hover background | rgb(240,240,240) |

Arrow tokens are shared with tooltip / dropdown and are not re-declared.

## Native state and content contract

Each of `open` and `current` has one control source. Controlled actions propose changes without storing a rejected proposal; removing control retains the last accepted value. Temporarily invalid or empty steps hide the guide without resetting its accepted index. A real reopening silently resets only an uncontrolled current index.

All native attributes, class, style and listeners land once on the actual popup root. Styles accept Vue objects, arrays and strings. Semantic precedence is Provider → top-level configuration → current step → native root attrs. Explicit `styles.root` retains its mask projection; native styles do not alter the positioning placeholder or mask.

Named slots are read while rendering. A present empty slot does not fall back to data. The actions scope contains a stable component: render it with `<component :is="originNode" />`. Step button callbacks remain data actions, receive a native `MouseEvent`, and can cancel navigation with `preventDefault()`.

Arrow navigation belongs to the guide panel and respects editable targets, IME and cancelled events. Escape affects only the top guide. Opening focuses the real popup without trapping interaction inside the target hole. Accepted closing restores owned focus while preserving an outside user choice. `mask=false` neither locks scrolling nor blocks page interaction.

The existing s53 target/ancestor ResizeObserver and captured scroll signals retain their frame-coalesced geometry. Close, target replacement and unmount release listeners, observations and pending frames. Reveal scrolling runs on step activation or target/options replacement rather than fighting passive scrolling. Pure position rearrangement without an observed size/scroll signal does not introduce a new DOM observer or polling loop.

Current Provider, locale and existing Token values are used by both Tour and PurePanel. Target getters may return `HTMLElement`, `null` or `undefined`; popup container services receive the actual placeholder and may return `HTMLElement`, `ShadowRoot` or pending `null`. Top-level layers use the current Tour Token, nested layers keep the existing parent offset, and explicit zero works.

### Migration

Use the Vue `popupAlign(element, align)` notification (`@popup-align`); programmatic `onPopupAlign` remains its listener. Render `actions.originNode` directly as a component, removing VNode casts and wrapper functions. Root attrs now belong to the visible popup; use `styles.mask` for mask customization. PurePanel accepts render fields plus `prefixCls/current/total`, not target/mask positioning inputs, and forwards the same named slots. Tour exposes no public imperative instance API.


## Basic (basic)

The most basic usage.

### 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>
```

## Custom mask (mask)

Custom mask style.

### 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 (non-modal)

Use `mask=false` to make Tour non-modal. At the meantime it is recommended to use with `type="primary"` to emphasize the guide itself.

### 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>
```

## Custom actions (actions-render)

Custom the actions with `#actions` slot (mapped to `actionsRender`). `originNode` is the default prev / next buttons group.

### 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>
```

## Custom indicator (indicator)

Custom the indicators with `#indicators` slot (mapped to `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 (placement)

The first step has no `target`, so the panel is displayed in the center of the screen. Other steps use `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;
```

## Custom highlight area (gap)

Using `gap` to control the radius of highlight area and the offset between highlight area and the element.

- Setting offset in two directions individually and `offset` with array type is supported.

### 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>
```

## Panel preview (render-panel)

Pure panel preview (debug usage, `TourPurePanel` = antd's `_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>
```

## Custom styles and classNames (style-class)

`styles` / `classNames` accept both object and function forms. When `styles` is a function, the argument contains `props`, so you can return different styles by component props (e.g. `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

Double-column transfer list.

## When to use

- Moving items between two groups with batch operations (select all / invert / per-page);
- Filtering or paginating large candidate lists;
- One-way shipping of items to a target list.

## Import

```ts
import { Transfer } from '@apollo-design/ui';
```

## Examples


















## API

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| dataSource | Data source, items must contain `key` | `TransferItem[]` | `[]` |
| targetKeys (`v-model:targetKeys`) | Target keys; controlled when provided, otherwise maintained internally | `TransferKey[]` | `[]` |
| selectedKeys (`v-model:selectedKeys`) | Checked keys; controlled when provided, otherwise maintained internally | `TransferKey[]` | - |
| titles | Titles of both lists | `VNodeChild[]` | `['', '']` |
| actions | Custom action texts `[toRight, toLeft]` | `VNodeChild[]` | arrows |
| disabled | Disable the whole component | `boolean` | `false` |
| showSearch | Show the search input | `boolean \| object` | `false` |
| showSelectAll | Show the select-all area in headers | `boolean` | `true` |
| oneWay | Hide the "move to left" action; right list renders remove buttons | `boolean` | `false` |
| pagination | Paginate the list body | `boolean \| object` | - |
| status | Validation status | `'error' \| 'warning'` | - |
| filterOption | Custom filter | `(inputValue, item, direction) => boolean` | text includes |
| rowKey | Key getter | `(record) => TransferKey` | `record.key` |
| selectAllLabels | Per-direction header labels | `[VNodeChild?, VNodeChild?]` | count text |

### Slots

| Name | Scope | Default |
| --- | --- | --- |
| item | `{ item, direction, selected, disabled }` | Data `title`, falling back to `key` for non-text titles |
| footer | `{ direction, selectedKeys, totalCount }` | No footer; count includes all items on that side |
| list | `{ direction, filteredItems, selectedKeys, disabled, onItemSelect, onItemSelectAll, onItemRemove, onScroll }` | Default list; internal pagination is disabled for a custom list |
| selectAllLabel | `{ direction, selectedCount, totalCount }` | Static `selectAllLabels` or default counts, based on filtered items |

Slots are read during rendering and support conditional insertion/removal. An explicitly empty slot stays empty. `direction` always denotes the data side (`left/right`), including RTL. Rich item content does not determine search text: search, row titles and checkbox names use data `title/key`; use `filterOption` for additional fields.

`onItemSelect(key, selected)` selects one item; `onItemSelectAll(keys, selected)` accepts `true`, `false` or `'replace'`. Selection callbacks exclude disabled and unlisted keys. `onItemRemove(keys)` removes items from the one-way right panel; `onScroll(event)` forwards scrolling. Custom controls should also bind `disabled`.

The current development version removes `render`, `footer`, `renderList` / `children` props and function entries in `selectAllLabels` directly. Use slots; there is no compatibility layer or deprecation period. See `docs/migrations/transfer-slots.md` (ADR 0006).

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:targetKeys | Request target keys for `v-model:targetKeys` | `(targetKeys)` |
| update:selectedKeys | Request checked keys for `v-model:selectedKeys` | `(selectedKeys)` |
| change | Request a move; controlled state follows the parent acceptance | `(targetKeys, direction, moveKeys)` |
| selectChange | Checked keys change | `(sourceSelectedKeys, targetSelectedKeys)` |
| search | Search value change (including clear) | `(direction, value)` |
| scroll | List scroll | `(direction, event)` |

Notifications use Vue emits, including listener arrays, without native fallthrough. Removing a controlled prop retains the last accepted state. Shift selection uses enabled items in the current filtered view and identifies its anchor by key after reordering.

### Refs and native attributes

`TransferRef.nativeElement` is the current root `HTMLElement`, or `null` after unmounting. `focus(options?: FocusOptions)` focuses the first enabled control in this instance; `blur()` only blurs a control within this instance. Native class/style/id/data attributes belong to the root. Native style accepts Vue objects, strings and arrays; semantic node styles use `CSSProperties`. Lengths retain explicit units; unitless properties such as opacity accept numbers, following native Vue styles.

### Statics

`Transfer.List` / `Transfer.Search` / `Transfer.Operation` (also exported as `TransferList` / `TransferSearch` / `TransferOperation`).

Static members and named exports have the same types. Search supports `v-model:value`, `@change` and `@clear`; replace `handleClear` with `@clear`. Operation uses `@move-to-right` / `@move-to-left`, directly replacing the `moveToRight/moveToLeft` callback props. List uses Vue filter/clear/selection/removal events; replace `handleFilter/handleClear` with `@filter/@clear`.

Text, icons and ordinary action content stay inside an owned button. Actual custom buttons retain Vue key/ref/directives and listener arrays. Header menus use named native buttons and support Enter.

### Current component tokens

Configure `listWidth`, `listHeight`, `listWidthLG`, `headerHeight`, `itemHeight`, `itemPaddingBlock` and `transferHeaderVerticalPadding` through `ConfigProvider.theme.components.Transfer`. Numeric lengths use px; CSS strings are preserved. Replacement, nesting and removal update current derived values. Native and semantic styles retain priority; `listStyle` stays below `styles.section`.


## Basic (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 (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>
```

## One way (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 (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` 开启列表面板内嵌分页（面板自动加宽，头部下拉多出「选择当前页」）。

### 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 (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)

`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 (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 (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 (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 (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>
```

## Custom Actions (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>
```

## Component 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>
```

## Semantic Styles (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

Display hierarchical data with expansion, selection, checking, asynchronous loading, dragging and virtual scrolling. Use `DirectoryTree` for folders.

```ts
import { Tree, DirectoryTree, type TreeProps, type TreeRef } from '@apollo-design/ui';
```

## Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| treeData | Data objects; use fieldNames for custom schemas and TreeProps<T> for typed data | object[] | - |
| fieldNames | Key, title and child field names | { key?, title?, children? } | key/title/children |
| expandedKeys | Controlled expansion (`v-model:expandedKeys`) | TreeKey[] | - |
| defaultExpandedKeys | Initial expansion | TreeKey[] | [] |
| defaultExpandAll | Initially expand nodes with children | boolean | false |
| defaultExpandParent | Initially include ancestors | boolean | true |
| autoExpandParent | Reactively include ancestors | boolean | false |
| checkable | Enable checkboxes or provide their content | boolean \| VNodeChild | false |
| checkStrictly | Independent checks; check emits { checked, halfChecked }. This does not determine whether state is controlled | boolean | false |
| checkedKeys | Controlled checks (`v-model:checkedKeys`) | SafeKey[] \| { checked, halfChecked } | - |
| defaultCheckedKeys | Initial checks | SafeKey[] | [] |
| selectable | Enable selection | boolean | true |
| multiple | Allow multiple selections | boolean | false |
| selectedKeys | Controlled selection (`v-model:selectedKeys`) | TreeKey[] | - |
| defaultSelectedKeys | Initial selection | TreeKey[] | [] |
| loadData | Load a node's children | (node) => Promise | - |
| loadedKeys | Controlled loaded state (`v-model:loadedKeys`) | SafeKey[] | - |
| showIcon | Show node icons | boolean | false |
| showLine | Show connecting lines and optional leaf content | boolean \| { showLeafIcon } | false |
| icon | Node icon content; use #icon for dynamic content | VNodeChild | - |
| switcherIcon | Expansion icon content; use #switcherIcon for dynamic content | VNodeChild | - |
| switcherLoadingIcon | Loading icon content | VNodeChild | - |
| blockNode | Fill each row | boolean | false |
| expandAction | Expand when clicking or double clicking a title | false \| 'click' \| 'doubleClick' | false |
| disabled | Disable the tree | boolean | inherited |
| draggable | Enable dragging, optionally per node | boolean \| predicate \| { nodeDraggable?, icon? } | false |
| allowDrop | Decide whether a computed position is allowed | ({ dragNode, dropNode, dropPosition }) => boolean | () => true |
| height | Virtual viewport height | number | - |
| itemHeight | Estimated row height; defaults to paddingXS/2 + titleHeight | number | derived |
| scrollWidth | Horizontal content width | number | - |
| virtual | Enable virtualization; inherits ConfigProvider | boolean | true |
| itemScrollOffset | Offset when following the active node | number | 0 |
| focusable | Allow tree focus | boolean | true |
| activeKey | Active node (`v-model:activeKey`); null clears | TreeKey \| null | - |
| tabIndex | Tree focus host tabindex | number | 0 |
| filterTreeNode | Mark matching nodes with the filter-node class | (node) => boolean | - |
| prefixCls | DOM class prefix; requires matching static CSS | string | apollo-tree |
| classNames / styles | root, item, itemIcon, itemTitle, itemSwitcher; object or { props } callback | object \| function | - |
| rootStyle | Root styles; native style is preferred | CSSProperties | - |

Controlled updates are proposals. Rejected proposals affect neither the current view nor the last accepted state retained when control is removed. Changes to data, multiple, checkStrictly and node capabilities reproject accepted keys without emitting user changes. `defaultExpandParent` applies once; `autoExpandParent` remains reactive.

Loads are deduplicated while pending. Refusing a successful loadedKeys proposal does not automatically repeat the request. Failure reports a warning; a subsequent expansion can retry. Results from replaced or removed nodes and unmounted trees are ignored.

## Events

`expandedKeys`, `checkedKeys`, `selectedKeys` and `loadedKeys` emit both `update:*` and their semantic event. `activeKey` emits `update:activeKey` and `activeChange`.

| Event | Arguments |
| --- | --- |
| 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 }); null when ended outside the tree |
| drop | (event: DragEvent, { node, dragNode, dragNodesKeys, dropPosition, dropToGap }) |

## Slots

Each slot receives `{ node, data }`: node contains the normalized key and current state; data is the original object, retaining mapped fields. A present slot takes priority even when it returns empty content.

| Slot | Description |
| --- | --- |
| title | Title, ahead of data title and data title functions |
| icon | Icon when showIcon is enabled, ahead of content props and data icons |
| switcherIcon | Expansion icon for expandable nodes |
| switcherLoadingIcon | Expansion icon while loading |

Top-level titleRender and icon/switcherIcon functions have moved to these slots. VNode content props, data-item title/icon/switcherIcon functions and algorithm/asynchronous callbacks remain supported. `<TreeNode>` children are unsupported; use treeData.

## TreeRef

| Member | Description |
| --- | --- |
| scrollTo(number \| { key, autoExpand?, offset?, align? } \| null) | Scroll by pixels or key; align is top/bottom. Without align, scroll only if needed. autoExpand requests all ancestors before scrolling. |
| focus() | Focus the actual tree container |
| keyEntities | Current read-only entity table. Numeric 0 and string '0' share one key representation and must not coexist. |

Native class/style land on the root. Semantic styles merge at their named region. The component owns node ids and checkbox labels for each tree instance.

## DirectoryTree

Also available as `Tree.DirectoryTree`. Defaults to showIcon=true, expandAction='click' and blockNode=true, with file/folder icons. Explicit false values and custom icons are honored. Multiple selection supports Shift ranges and Ctrl/Meta toggling. All Tree model, semantic and native events are forwarded, with the same controlled boundaries. defaultExpandAll includes every entity key. DirectoryTree does not declare a separate ref API.

## Component tokens

All values follow the current theme and can be overridden through `components.Tree`. Dimensions accept numbers in pixels.

| Token | Default |
| --- | --- |
| titleHeight | controlHeightSM (24px) |
| switcherSize | controlHeightSM |
| indentSize | controlHeightSM |
| nodeHoverBg | controlItemBgHover |
| nodeHoverColor | colorText |
| nodeSelectedBg | controlItemBgActive |
| nodeSelectedColor | colorText |
| directoryNodeSelectedBg | colorPrimary |
| directoryNodeSelectedColor | colorTextLightSolid |

Examples for expansion, checks, folders, async loading, dragging, virtual scrolling, imperative scrolling and all nine tokens are linked in [the example catalog](https://github.com/apollocmh/apollo-design-ui/blob/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/tree/index.zh-CN.md#代码演示).


## Block Node (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

Select hierarchical data with single or multiple values, check conduction, filtering, async loading and virtual scrolling. Each node value also serves as its tree key.

## Props

| Prop | Contract | Default |
| --- | --- | --- |
| value / defaultValue | TreeSelectValue; a scalar for single selection, an array for multiple selection, labeled objects with labelInValue | - |
| treeData / fieldNames | TreeSelectDataNode[] and optional value/label/children field mapping | [] |
| multiple / treeCheckable / treeCheckStrictly | Multiple selection, cascading checks, or independent checks; strict checks retain halfChecked metadata and enable labelInValue | false |
| showCheckedStrategy / maxCount | SHOW_ALL, SHOW_PARENT or SHOW_CHILD; maxCount is ignored for SHOW_PARENT and non-strict SHOW_ALL | SHOW_CHILD for checks, otherwise SHOW_ALL |
| treeDataSimpleMode | Build a tree from flat data; optional id/pId/rootPId mapping | false |
| loadData | (node) => Promise<unknown>; a business service, disabled during search | - |
| treeExpandedKeys / treeDefaultExpandedKeys / treeDefaultExpandAll | Controlled/default expansion and initial expand-all | - / - / false |
| treeLoadedKeys | Controlled loaded keys | - |
| treeExpandAction / treeLine | Content-click expansion and connector lines | false |
| treeIcon / showTreeIcon / switcherIcon | Node-data icons, visibility and a static switcher icon; use slots for stateful rendering | - |
| showSearch / searchValue | boolean or SearchConfig; search state belongs to the top-level model | false / '' |
| filterTreeNode / treeNodeFilterProp / autoClearSearchValue | Filtering and clearing algorithms; values in the showSearch object take precedence | Match value / true |
| treeNodeLabelProp / labelInValue | Selected-label field and labeled value shape | title or label / false |
| placeholder / notFoundContent / suffixIcon / clearIcon / removeIcon | Static VNodeChild content; the corresponding slot takes priority | - |
| allowClear | boolean or { clearIcon, label } | false |
| maxTagCount / maxTagTextLength / maxTagPlaceholder | Tag limits and static overflow content | - |
| disabled / loading / size / status / variant | Current disabled, loading, size, validation and appearance settings | Inherited where applicable |
| open / defaultOpen / placement / direction | Controlled/default popup state, placement and direction | false / bottomLeft / ltr |
| getPopupContainer / popupMatchSelectWidth | Container and width; false also disables virtualization | Inherited / true |
| listHeight / listItemHeight / virtual | List height, row height and virtualization; default row height follows the current Tree tokens | 256 / 28 / true |
| classNames / styles | Semantic objects or ({ props }) => objects, receiving current TreeSelectProps | - |
| id / tabIndex / autoFocus / maxLength | Native input identity, focus and input limit | - |

The five states support `v-model:value`, `v-model:open`, `v-model:searchValue`, `v-model:treeExpandedKeys` and `v-model:treeLoadedKeys`. A rejected controlled request preserves accepted state; releasing control keeps the last accepted value.

Native class/style reach the trigger once and remain current, including removal. aria-label/aria-labelledby target the real combobox input. Other native attrs/listeners follow BaseSelect's root contract. The default slot accepts one native button or a component that forwards native attrs as a custom trigger.

Existing aliases bordered, dropdownMatchSelectWidth, popupClassName and dropdownClassName remain available. Prefer variant, popupMatchSelectWidth and semantic popup.root styles. popupStyle remains an explicit popup style input.

## Events

| Event | Payload |
| --- | --- |
| change / update:value | change(value, labels, extra); update:value(value). labels is null with labelInValue. extra includes preValue, triggerValue and checked/selected |
| select / deselect | (rawValue, dataNode) |
| openChange / update:open | (open: boolean) |
| search / update:searchValue | (text: string); search reports input actions, automatic clearing updates only the model |
| treeExpand / update:treeExpandedKeys | (keys) |
| treeLoad / update:treeLoadedKeys | (keys) |
| clear | No payload |
| popupScroll / focus / blur / inputKeyDown | Native Event / FocusEvent / FocusEvent / KeyboardEvent |

Listening to change never changes the model shape. Historical triggerNode/allCheckedNodes data getters retain their deprecation warnings. Use openChange instead of the removed popup/dropdown visibility notification aliases.

## Slots

| Slot | Scope |
| --- | --- |
| default | One custom trigger |
| treeTitleRender | { node: TreeSelectDataNode }, for tree titles and selected labels |
| treeIcon / switcherIcon / switcherLoadingIcon | { node, data }, with current runtime state and original data |
| tagRender | { label, value, disabled, closable, onClose, isMaxTag } |
| popupRender | { menu } |
| maxTagPlaceholder | { omittedValues } |
| suffixIcon | { searchValue, open, focused, showSearch, loading } |
| prefix / placeholder / notFoundContent / clearIcon / removeIcon / loadingIcon | No scope |

Slots are read during render; their presence takes priority, including an empty result or numeric 0. Migrate top-level treeTitleRender, tagRender and popupRender/dropdownRender function props to slots; migrate switcherIcon functions to its slot. This development migration has no compatibility channel or deprecation period. Node-data title/icon functions, filter algorithms and async loadData services retain their business roles.

## Ref

TreeSelectRef exposes focus(options?: FocusOptions), blur(), scrollTo(number | { key, align?, offset?, autoExpand? } | null) and the current nativeElement: HTMLElement | null property. The property replaces the old nativeElement() method.

## Configuration and theme

Current components.treeSelect presentation settings provide className/style, semantic classNames/styles, showSearch/allowClear and static icons. Replacement and removal remain reactive. Global direction, container, size, disabled, variant and virtual settings retain their separate responsibilities.

There is no independent TreeSelect token entry. Tree nodes share the current nine components.Tree tokens; the selector shares current components.Select tokens. Variables accompany both the trigger and teleported popup. Explicit listItemHeight wins; otherwise rows follow Tree titleHeight and padding. Popup layering retains parent-context rules, and explicit popupStyle or semantic popup.root zIndex preserves 0.

SHOW_ALL, SHOW_PARENT and SHOW_CHILD are available as named exports and TreeSelect static properties. The deprecated TreeSelect.TreeNode children-data form is not supported.


## Component 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)

使用 `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 (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 (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


Titles, paragraphs, inline text and links with copy, edit and ellipsis controls.

## Examples

The 14 demos cover formatting, five heading levels, semantic colours, copying, editing, controlled expansion, middle ellipsis, suffixes, component tokens, semantic styling and a Table consumer.

## API

```ts
import { Typography, Text, Title, Paragraph, Link } from '@apollo-design/ui';
import '@apollo-design/ui/style.css';
```

Named exports are identical to `Typography.Text / Title / Paragraph / Link`. The component stylesheet is `@apollo-design/ui/typography/style.css`; applications also need theme and base styles.

### Components and content

| Component | Native root | Features |
|---|---|---|
| Typography | article; component selects another tag | Container and semantic styling |
| Text | span | Decorations, copy, edit, single-line ellipsis |
| Title | h1…h5; level defaults to 1 | Decorations, copy, edit, ellipsis |
| Paragraph | div | Decorations, copy, edit, multiline ellipsis |
| Link | span containing a native anchor | Link, decorations, copy, edit, boolean ellipsis |

All five accept a default slot containing text, Fragments, conditional nodes, elements and Vue components. The four fixed semantic components exclude component; use Typography for a custom container tag. Title excludes strong.

Link places copy/edit buttons beside its anchor. href, target, rel, link ARIA, tabindex and native events reach the anchor; id, class, style and expose belong to the outer root. A blank target supplies noopener noreferrer unless rel is explicitly provided. Disabled links expose aria-disabled, leave the Tab order and block activation.

### Shared props and native attrs

| Prop | Type / default | Meaning |
|---|---|---|
| prefixCls | string | Current ConfigProvider prefix; apollo-typography by default |
| direction | 'ltr' \| 'rtl' | Current Provider direction |
| classNames | object or ({ props }) => object | root / actions / action / textarea classes |
| styles | object or ({ props }) => object | CSSProperties for the same semantic nodes |
| component | string; article | Typography only |

Root class, style, id and data attributes use native Vue attrs, including replacement and removal. Classes merge; native style overrides styles.root. Semantic callbacks receive BaseTypographyProps. ConfigProvider components.typography supports class, style and semantic configuration; replacing or removing it preserves business slot and editor identity.

### Text / Title / Paragraph / Link props

| Prop | Type / default | Meaning |
|---|---|---|
| type | 'secondary' \| 'success' \| 'warning' \| 'danger' | Semantic text colour |
| disabled | boolean; false | Disabled styling; Link also blocks activation |
| copyable | boolean \| CopyConfig | Copy control |
| editable | boolean \| EditConfig | Inline editor |
| ellipsis | boolean \| EllipsisConfig | Text excludes rows / expandable / onExpand; Link accepts only boolean |
| strong / underline / delete / code / mark / keyboard / italic | boolean; false | Decorations; Title excludes strong |
| actions | { placement?: 'start' \| 'end' } | Operation placement; end by default |
| title | string | Native title and ellipsis title candidate |
| level | 1 \| 2 \| 3 \| 4 \| 5; 1 | Title only |
| target / rel | string | Link only; href is a native attr |

### CopyConfig

| Field | Type / default | Behaviour |
|---|---|---|
| text | string \| (() => string \| Promise<string>) | Content text when absent; an empty string copies empty text |
| onCopy | (event?: MouseEvent) => void | Called only after a successful write |
| icon / tooltips | VNodeChild \| [VNodeChild, VNodeChild] | Exactly two array entries are a before/after pair; other lengths remain complete content |
| format | 'text/plain' \| 'text/html' | Clipboard format |
| tabIndex | number | Copy button Tab order |

False tooltips disable the popup. Defaults use the current locale. Pending requests reject duplicate activation. Failures do not report success, and unmount prevents late state updates and callbacks. Custom icons keep a native button and accessible name.

### EditConfig

| Field | Type / default | Behaviour |
|---|---|---|
| text | string | Initial editor text; otherwise recognisable plain content |
| editing | boolean | Controlled editing state; omit for uncontrolled use |
| onStart / onCancel / onEnd | () => void | Enter editing, cancel, Enter-save completion |
| onChange | (value: string) => void | Save on Enter or blur; trim outer whitespace, preserve internal newlines |
| icon / tooltip / enterIcon | VNodeChild | Edit icon, full tooltip content and confirm icon; false tooltip disables it, null enterIcon hides it |
| triggerType | ('icon' \| 'text')[]; ['icon'] | Text-only mode retains a native keyboard entry |
| autoSize | boolean \| { minRows?: number; maxRows?: number }; true | Resize for content, width and current configuration |
| maxLength / tabIndex | number | Editor limit / edit button Tab order |

The editor fills its host and reserves space for the confirm icon. With autoSize false it still displays a complete native row. Border, background and focus follow the current theme; styles.textarea can explicitly override native styling.

Enter saves and Escape cancels. Modified Enter retains native multiline behaviour; IME composition never submits. Controlled callbacks request a transition; the parent decides whether to close. Accepted keyboard completion restores edit-button focus; blur to another control preserves that destination.

aria-label, aria-labelledby and aria-describedby reach the textarea. Without a supplied name, plain content or the current locale supplies one. Root attrs and expose remain available while editing.

### EllipsisConfig

| Field | Type / default | Behaviour |
|---|---|---|
| rows | number; 1 | Floor positive finite values; otherwise use 1 |
| expandable | boolean \| 'collapsible'; false | Enable expansion; collapsible also allows collapse |
| suffix | string | Content after ellipsis |
| symbol | VNodeChild \| ((expanded: boolean) => VNodeChild) | Expand/collapse label |
| expanded / defaultExpanded | boolean | Controlled state / uncontrolled initial state |
| onExpand | (event: MouseEvent, info: { expanded: boolean }) => void | Expansion request |
| onEllipsis | (ellipsis: boolean) => void | Actual ellipsis-state changes |
| tooltip | VNodeChild \| { title?: VNodeChild } | True uses original content; false disables it |

Simple cases use CSS. Operations, suffixes and expansion use actual width measurement. Hidden probes project mounted native content without mounting business Vue components again. Width, rows, content and font changes remeasure; obsolete and unmounted work is cancelled.

### Slots, events, models and expose

The only slot is default. There are no component emits or v-model bindings; edit and expansion use their configuration values and callbacks. The readonly TypographyRef.nativeElement exposes the actual current root or null, including editing; Link exposes its outer root.

### Component tokens

Set theme.components.Typography on ConfigProvider. Numbers become px; zero, replacement and removal work.

| Token | Default | Consumer |
|---|---|---|
| titleMarginTop | 1.2em | Top margin of headings following content |
| titleMarginBottom | 0.5em | Heading bottom margin |

Default semantic and operation text follows the current colour scheme with readable contrast. Native style is an explicit override; custom foregrounds require an appropriate background.


## Basic (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 (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 & decorations (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 (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)

`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 (editable)

`triggerType` chooses how editing starts: `['icon']` (the pencil button, by default) or `['text']` (the text itself).

Enter saves, Escape cancels and blur saves. Saved values are trimmed. Enter does not save during IME composition or while Ctrl, Alt, Meta or Shift is held.

The last example uses a conditional default slot in a normal Vue template. It initially has no body. Update the text, then reveal, edit or copy it: each operation reads the current content. Removing the body restores the copy button's icon-only state. Editing uses a native `<textarea>` with an explicit accessible name.

### 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>
```

## Semantic classNames / styles (semantic)

The four semantic regions are `root`, `actions`, `action` and the editing-only `textarea`. `classNames` joins classes, while `styles` merges styles for the same region. Function configs receive `{ props }` with the resolved `prefixCls` and `direction`.

The object, function and action examples are preserved. The final example cycles native Vue `class` / `style` through a dynamic string, mixed array, object and removal. Native style overrides `styles.root`; removing it restores the semantic root. Style updates preserve the input's draft and focus.

The scoped ConfigProvider example also replaces the whole `components.typography` configuration: object, new object, new functions that capture current plain values, then removal. Root, action group, buttons and editing input update together. Callbacks read the existing `props.prefixCls` field and receive its resolved value. Native root style and local `styles.root` keep their priority; replacing configuration preserves drafts and focus.

### 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-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>
```

## Controlled Ellipsis (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>
```

## Expandable (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>
```

## Custom Editable (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>
```

## Ellipsis Suffix (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>
```

## Typography in Table (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>
```

## Component Token (component-token)

Cycle the two existing title-spacing tokens through defaults, custom values and zero. Top spacing applies to headings following typography content. The native heading variables demonstrate font size and weight; body and secondary text retain the current theme.

### 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


Upload files by selecting or dragging.

## When To Use

- Upload is the process of publishing information (web pages, text, pictures, video, etc.)
  to a remote server via a web page or an upload tool.
- When you need to upload one or more files.
- When you need to show the process of uploading.
- When you need to use drag and drop interaction.

## Examples

See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/upload/demo) (23 demos).

| demo | Content |
|---|---|
| `basic` | Click to upload: controlled `v-model:fileList` with done / uploading / error items |
| `dragger` | Drag area (`UploadDragger`) with the `-drag-hover` state |
| `picture-card` | Picture wall: thumbnails plus the hover action layer |

Scenarios such as image cropping, external OSS uploads and custom progress bars need
external services or extra capabilities and are not provided. The upload lifecycle,
validation, drag / picture wall, manual upload and custom request paths are covered.

## API

### Props

| Property | Description | Type | Default |
|---|---|---|---|
| action | Upload URL. A function receives the file and may return a promise | `string \| ((file: RcFile) => string \| PromiseLike<string>)` | — |
| accept | Accepted file types (`string`, or `{ format, filter: 'native' \| (file) => boolean }`) | `string \| AcceptConfig` | — |
| beforeUpload | Hook before uploading. Return `false` to stop (still emits `change` once), `LIST_IGNORE` to skip entirely, or a `File`/`Blob`/string to replace the payload. A rejected hook stops that file | `(file: RcFile, fileList: RcFile[]) => void \| boolean \| string \| Blob \| Promise<…>` | — |
| capture | Media capture, forwarded to the native input | `string \| boolean` | — |
| classNames | Semantic class names: `{ root, trigger, list, item }` (or a function) | `UploadSemanticClassNames \| ((info) => …)` | — |
| customRequest | Replace XHR; the second argument provides `defaultRequest`. Return an abort handle to cancel the request | `(options, { defaultRequest }) => { abort: () => void } \| void` | — |
| data | Extra form data (function form is evaluated per file) | `object \| ((file: RcFile) => object \| Promise<object>)` | `{}` |
| defaultFileList | Default file list (uncontrolled) | `UploadFile[]` | — |
| directory | Upload a folder (recursed by `traverse-file-tree`) | `boolean` | — |
| disabled | Whether disabled | `boolean` | — |
| fileList | Controlled file list (same as `v-model:fileList`) | `UploadFile[]` | — |
| headers | Request headers (`null` values are skipped) | `Record<string, string \| null>` | — |
| isImageUrl | Override the "is image" predicate | `(file: UploadFile) => boolean` | Built-in predicate |
| listType | List style | `'text' \| 'picture' \| 'picture-card' \| 'picture-circle'` | `'text'` |
| maxCount | Max number of files. With `1`, a new file replaces the old one; exceeded files never enter the list and do **not** emit `change` | `number` | — |
| method | Request method | `string` | `'post'` |
| multiple | Whether multiple selection is allowed | `boolean` | `false` |
| name | Field name sent to the server | `string` | `'file'` |
| onPreview | Replace preview navigation | `(file: UploadFile) => void` | — |
| onDownload | Replace the default download service | `(file: UploadFile) => void` | — |
| onRemove | Confirm removal; false prevents it | `(file: UploadFile) => void \| boolean \| Promise<void \| boolean>` | — |
| openFileDialogOnClick | Whether clicking the trigger opens the file dialog | `boolean` | `true` |
| pastable | Paste from clipboard (document-level listener) | `boolean` | — |
| previewFile | Custom thumbnail generator for the picture family | `(file: File \| Blob) => PromiseLike<string>` | 200×200 centered thumbnail |
| progress | Upload-list progress presentation options, detailed below | `UploadListProgressProps` | Full width, 2px, no information |
| showUploadList | Show the list, or configure it: `{ showPreviewIcon, showRemoveIcon, showDownloadIcon }` | `boolean \| ShowUploadListInterface` | `true` |
| type | `'drag'` is equivalent to using `UploadDragger` | `'select' \| 'drag'` | `'select'` |
| withCredentials | Whether to send cookies on cross-origin requests | `boolean` | `false` |
| class / style | Native attrs on the outer wrapper; local style wins over semantic root style | — | — |
| hasControlInside | Whether the trigger already contains a focusable control (drives `role="button"` / `tabIndex` on the engine root) | `boolean` | `true` |
| locale | Override built-in text | `{ uploading, removeFile, downloadFile, previewFile }` | from `LocaleProvider` |

`onPreview(file)` and `onDownload(file)` are service Props: supplying them replaces
native preview navigation or the default `window.open` download. `onRemove(file)` is
an optional confirmation Prop; `false` or a promise resolving to false keeps the file.
These callbacks do not also emit notification events.

`fileList` owns the accepted list. An update is a proposal; rejecting it does not mutate
the parent's files, and removing the binding keeps the last accepted list. Removing or
replacing an accepted active file aborts its request; late callbacks cannot update it.
`maxCount` also excludes excess requests. Action/data/request failures mark that file
as error while other files in the batch continue. A stopped beforeUpload file still
produces an UploadFile payload with originFileObj and no uploading status.

Native `class` and `style` belong to the wrapper. Other native attrs/listeners target
the interactive trigger, and `id`/`name` target the real file input. With no internal
control, Enter and Space activate the trigger; disabled triggers leave the tab order.
UploadDragger forwards all Upload slots, callbacks, model events and refs; `height`
sets the wrapper height and defaults hasControlInside to false.

### Progress options

| Field | Description | Type | Default |
|---|---|---|---|
| strokeColor | Solid color, `{ from, to }`, or percentage gradient stops; gradient direction follows RTL | `string \| Record<string, string>` | Theme progress color |
| strokeWidth | Rail thickness; numbers use px, strings use valid CSS lengths | `number \| string` | `2` |
| showInfo | Show the current percentage | `boolean` | `false` |
| size | A number sets width and height; a tuple sets `[width, height]`. Nonpositive width fills the available space. small/default use 6/8px thickness | `number \| [number, number] \| 'small' \| 'default'` | `[-1, 2]` |
| aria-label | Accessible name on the actual bar; overrides the file value and falls back to the file name | `string` | File name |
| aria-labelledby | Label element IDs on the actual bar; overrides the file value | `string` | — |

A numeric or tuple size determines dimensions. Otherwise, explicit strokeWidth takes
precedence over presets and the default thickness. Partial progress objects retain
the full-width 2px default. Current `components.upload.progress` Provider options are
shallow-merged with local options; local fields win, including reactive replacement and removal.

The value comes from `UploadFile.percent`: finite fractions are preserved and clamped
to 0–100; non-finite values become 0. An absent percent field omits the bar, while
explicit undefined or 0 means zero progress. After a 300ms delay from the list item's
initial mount, the bar is shown only while uploading. Reaching 100% still waits for
the upload success event. A whole-row itemRender slot owns its content. This subset
does not expose other Progress fields such as percent/type/status.

### Events

| Event | Description | Arguments |
|---|---|---|
| `update:fileList` | Controlled update (`v-model:fileList`) | `fileList` |
| `change` | Emitted once per state transition (uploading / done / error / removed); emitted **per file** on batch start | `{ file, fileList, event? }` |
| `drop` | Drop event (event channel only) | `DragEvent` |

### Slots

| Name | Scope | Description |
|---|---|---|
| default | — | Trigger content. With `type="drag"` it lands in `-drag-container`; with `picture-card` / `picture-circle` it becomes the trailing upload button |
| iconRender | `{ file, listType }` | Custom list item icon (was the `iconRender` prop) |
| itemRender | `{ originNode, file, fileList, actions }` | Customize the whole list item (was the `itemRender` prop) |
| removeIcon | `{ file }` | Custom remove icon (was `showUploadList.removeIcon`) |
| previewIcon | `{ file }` | Custom preview icon (was `showUploadList.previewIcon`) |
| downloadIcon | `{ file }` | Custom download icon (was `showUploadList.downloadIcon`) |
| extra | `{ file }` | Custom list item extra content (was `showUploadList.extra`) |
| appendAction | — | Trailing upload trigger content for picture-card/circle; preserves the file input and all returned nodes. A present empty slot takes precedence |

### Expose

| Name | Description |
|---|---|
| `nativeElement` | Root element (`HTMLElement \| null`) |
| `fileList` | Current file list |
| `upload` | Engine handle: `abort(fileOrUid?)`, `uploadFiles(files): Promise<void>`, `getInputRef()` |
| `onBatchStart` / `onSuccess` / `onProgress` / `onError` | Programmatic lifecycle hooks; the engine normally calls these itself |

### Types

`UploadFile`, `UploadProps`, `UploadChangeParam`, `UploadListType`, `ItemRender`,
`ShowUploadListInterface`, `UploadLocale`, `UploadRef`, `UploadSlots`, `UploadConfig`, `DraggerProps`, `RcFile` (= `File & { uid }`),
`LIST_IGNORE` (sentinel for `beforeUpload`).

Thumbnail generation is local state: it starts on mount, reruns when its source or
handler changes, and does not write thumbUrl into controlled files. Removed sources
and unmounted lists ignore late results; built-in image resources are released.
Current `theme.components.Upload` supports actionsColor and pictureCardSize; native
CSS variables may override both. The default card size follows controlHeightLG.

The unused supportServerRender and styleAttrs fields were removed in the 0.0.0
development version. SSR works directly; use native style for root styling. There is
no compatibility layer or deprecation period for these fields.

## Design Notes

- **Self-built upload engine**: the five modules under `engine/` are equivalents of
  `@rc-component/upload` (depending on rc packages is forbidden). `customRequest`
  is the single replacement point; the default goes through XHR + FormData.
- **Custom requests**: `customRequest` is the replacement point; the default uses
  XHR + FormData.
- **List motion**: non-picture styles expand/collapse by height, picture styles fade;
  `motionName = {p}-animate[-inline]` with a 2000ms fallback.
- **Progress**: upload-specific presentation options compose the shared Progress component.
  Error messages use native `title` tooltips.
- **No global base styles**: for a bare `<a>` name or a native `<button>` trigger, the
  link color and form-control normalization come from your own global CSS.
  Pair the library with any CSS reset, or use the bundled `Button` / `Link`.


## Basic (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>
```

## Drag and Drop (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>
```

## Pictures Wall (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 (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 & Validation (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 (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 (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>
```

## Upload Error (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 List (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 (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)

设置 `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 (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>
```

## Upload Manually (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>
```

## List Actions (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)

把 `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>
```

## Component 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 (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 (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 (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 (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 (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>
```

## Upload PNG Only (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 (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


Add a decorative watermark without blocking content or interaction. See [`demo/`](https://github.com/apollocmh/apollo-design-ui/tree/b6578306f58bf0918d0f4cb8519cf4cf1a900b15/packages/ui/src/watermark/demo) for text, multiple lines, images, reactive configuration and inheritance into Modal.

## API

| Prop | Description | Type | Default |
|---|---|---|---|
| content | Text; an array draws multiple lines, each with optional font overrides | `WatermarkContent \| WatermarkContent[]` | — |
| font | Font settings below | `WatermarkFont` | `colorFill`, `fontSizeLG`, normal sans-serif |
| image | Image URL, preferred over text; load failure draws `content` | `string` | — |
| width / height | Size of one watermark unit | `number` | measured text / 120×64 image |
| rotate | Rotation in degrees | `number` | `-22` |
| gap | Spacing `[x, y]` | `[number, number]` | `[100, 100]` |
| offset | Offset `[left, top]`; drawing anchor is `offset - gap / 2` | `[number, number]` | `gap / 2` |
| zIndex | Decoration layer, including `0` | `number` | `zIndexPopupBase - 1` |
| inherit | Registered descendant overlays use this watermark; when false, registration passes to the ancestor, or remains uncovered without one | `boolean` | `true` |

Native `class`, `style`, `id`, `aria-*` and events land on the root `div`. Style precedence is default `position: relative; overflow: hidden` → Provider style → native `style`. Vue style objects, arrays and strings work. Tamper recovery respects the current legitimate overrides.

### Font

| Field | Type | Default |
|---|---|---|
| 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'` |

Numbers and numeric strings use pixels. Valid sizes such as `16px`, `2rem`, `12pt` and `calc(...)` are parsed by native canvas; its normalized pixel size drives measurement and scaling. Relative units are evaluated on redraw; external font loading and page font-size changes are not separately observed. A font rejected by the browser throws `TypeError` during drawing instead of silently reusing the previous font. Undefined per-line fields inherit the current effective font.

### Slots and events

| Slot | Description |
|---|---|
| default | Native covered content, without scoped arguments; ordinary configuration updates retain its subtree |

| Event | Description | Arguments |
|---|---|---|
| remove | Notifies once when a managed watermark node is restored after removal or reparenting. Initial drawing, deliberate inheritance changes and normal unmount do not notify | None |

Use `<Watermark @remove="notify">`. In programmatic calls, `onRemove` is a Vue listener with replacement and `.once` support, rather than a callback prop.

### Ref

`WatermarkRef.nativeElement: HTMLDivElement | null` returns the current root. SSR renders only the root and default slot. Canvas, images and observers start after mounting. Unmount cancels pending frames, releases image callbacks and observers, and removes managed overlay watermarks.

### Theme

There is no stylesheet or Component Token. Drawing consumes current `zIndexPopupBase`, `colorFill` and `fontSizeLG` alias values, including Provider replacement and removal.

### Migration

Tamper notification is the native Vue `remove` event. Replace invalid `fontStyle: 'none'` with `'normal'`. Changing an image URL now invalidates a same-size cache entry without also changing width or height.


## Basic (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)

通过数组设置多行水印，每一行都可以有独立的字体配置。

### 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)

通过 `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)

Adjust the watermark with Apollo inputs, color picker, sliders and number inputs. The preview and controls wrap to fit the container. Empty offsets use the default placement.

### 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>
```

## Inherit Into Portal (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>
```